solver-sdk 3.1.2 → 3.1.3

package/docs/indexing/INDEXING.md

@@ -1,759 +0,0 @@
-# 📊 Руководство по индексации проектов
-
-## 🚀 Быстрый старт
-
-```javascript
-import { CodeSolverSDK } from 'solver-sdk';
-
-const sdk = await CodeSolverSDK.create({
-  baseURL: 'http://localhost:3000'
-});
-
-// 1. Создать/найти проект → 2. Запустить индексацию → 3. Мониторить прогресс
-const project = await sdk.projects.findOrCreateProject('/path/to/project', 'Project Name');
-await sdk.projects.startIndexing(project.id);
-
-// Ожидание завершения
-while (true) {
-  const status = await sdk.projects.getProjectStatus(project.id);
-  if (status.status === 'ready') break;
-  await new Promise(resolve => setTimeout(resolve, 2000));
-}
-```
-
-## 📋 Основные методы индексации
-
-### 1. Поиск/создание проекта
-
-```typescript
-// Найти существующий или создать новый проект
-const project = await sdk.projects.findOrCreateProject(
-  projectPath: string,
-  projectName?: string
-): Promise<Project>
-
-// Примеры:
-const project1 = await sdk.projects.findOrCreateProject('/path/to/my-project');
-const project2 = await sdk.projects.findOrCreateProject('/path/to/my-project', 'My Project');
-```
-
-**Результат:**
-```typescript
-interface Project {
-  id: string;           // "12345678-1234-1234-1234-123456789012"
-  name: string;         // "My Project"
-  path: string;         // "/path/to/my-project"
-  status: 'idle' | 'indexing' | 'ready' | 'error';
-  createdAt: string;    // "2024-01-01T12:00:00Z"
-  updatedAt: string;    // "2024-01-01T12:00:00Z"
-}
-```
-
-### 2. Запуск индексации
-
-```typescript
-// Запустить индексацию проекта
-await sdk.projects.startIndexing(
-  projectId: string,
-  options?: IndexingOptions
-): Promise<IndexingResponse>
-
-// Примеры:
-await sdk.projects.startIndexing(project.id);
-
-await sdk.projects.startIndexing(project.id, {
-  forceFull: true,           // Полная переиндексация
-  excludePatterns: ['node_modules/**', '*.log']
-});
-```
-
-**Опции индексации:**
-```typescript
-interface IndexingOptions {
-  forceFull?: boolean;      // Полная переиндексация (по умолчанию: false)
-  excludePatterns?: string[]; // Паттерны исключения
-  includePatterns?: string[]; // Паттерны включения
-  maxFileSize?: number;     // Максимальный размер файла (байты)
-}
-```
-
-### 3. Мониторинг статуса
-
-```typescript
-// Получить текущий статус проекта
-const status = await sdk.projects.getProjectStatus(
-  projectId: string
-): Promise<ProjectStatus>
-```
-
-**Статус индексации:**
-```typescript
-interface ProjectStatus {
-  status: 'idle' | 'indexing' | 'ready' | 'error';
-  progress?: number;        // 0-100
-  totalFiles?: number;      // Общее количество файлов
-  processedFiles?: number;  // Обработано файлов
-  currentFile?: string;     // Текущий обрабатываемый файл
-  error?: string;          // Текст ошибки (если status === 'error')
-  startTime?: string;      // Время начала индексации
-  estimatedTime?: number;  // Примерное время завершения (секунды)
-}
-```
-
-### 4. Управление индексацией
-
-```typescript
-// Отменить индексацию
-await sdk.projects.cancelIndexing(projectId: string): Promise<boolean>
-
-// Очистить ошибку индексации
-await sdk.projects.clearIndexingError(projectId: string): Promise<boolean>
-
-// Удалить проект
-await sdk.projects.deleteProject(projectId: string): Promise<void>
-```
-
-### 5. Получение списка проектов
-
-```typescript
-// Все проекты
-const allProjects = await sdk.projects.getAllProjects(): Promise<Project[]>
-
-// Только готовые к работе проекты (проиндексированные)
-const readyProjects = await sdk.projects.getReadyProjects(): Promise<Project[]>
-
-// Конкретный проект
-const project = await sdk.projects.getProject(projectId: string): Promise<Project>
-```
-
-## 🔄 Workflow индексации
-
-### Простой workflow
-
-```javascript
-async function simpleIndexing(projectPath, projectName) {
-  const sdk = await CodeSolverSDK.create({
-    baseURL: 'http://localhost:3000'
-  });
-  
-  try {
-    // 1. Создать/найти проект
-    console.log('📁 Создание проекта...');
-    const project = await sdk.projects.findOrCreateProject(projectPath, projectName);
-    console.log(`✅ Проект создан: ${project.id}`);
-    
-    // 2. Запустить индексацию
-    console.log('🚀 Запуск индексации...');
-    await sdk.projects.startIndexing(project.id);
-    
-    // 3. Ожидание завершения
-    console.log('⏳ Ожидание завершения...');
-    while (true) {
-      const status = await sdk.projects.getProjectStatus(project.id);
-      
-      if (status.status === 'ready') {
-        console.log('✅ Индексация завершена!');
-        break;
-      } else if (status.status === 'error') {
-        throw new Error(`Ошибка индексации: ${status.error}`);
-      }
-      
-      // Показать прогресс
-      if (status.progress) {
-        console.log(`📊 Прогресс: ${status.progress}%`);
-      }
-      
-      await new Promise(resolve => setTimeout(resolve, 2000));
-    }
-    
-    return project;
-    
-  } catch (error) {
-    console.error('❌ Ошибка:', error.message);
-    throw error;
-  }
-}
-
-// Использование
-const project = await simpleIndexing('/path/to/my-project', 'My Project');
-```
-
-### Продвинутый workflow с обработкой ошибок
-
-```javascript
-async function advancedIndexing(projectPath, options = {}) {
-  const sdk = await CodeSolverSDK.create({
-    baseURL: 'http://localhost:3000'
-  });
-  
-  const {
-    projectName = 'Auto Project',
-    timeout = 300000,      // 5 минут
-    retryAttempts = 3,
-    excludePatterns = ['node_modules/**', '*.log', '.git/**']
-  } = options;
-  
-  let project;
-  let attempt = 0;
-  
-  while (attempt < retryAttempts) {
-    try {
-      attempt++;
-      console.log(`🔄 Попытка ${attempt}/${retryAttempts}`);
-      
-      // 1. Создать/найти проект
-      project = await sdk.projects.findOrCreateProject(projectPath, projectName);
-      console.log(`📁 Проект: ${project.name} (${project.id})`);
-      
-      // 2. Проверить текущий статус
-      let status = await sdk.projects.getProjectStatus(project.id);
-      
-      // Если уже готов - возвращаем
-      if (status.status === 'ready') {
-        console.log('✅ Проект уже проиндексирован');
-        return project;
-      }
-      
-      // Если есть ошибка - очищаем
-      if (status.status === 'error') {
-        console.log('🧹 Очистка предыдущей ошибки...');
-        await sdk.projects.clearIndexingError(project.id);
-      }
-      
-      // Если идет индексация - отменяем
-      if (status.status === 'indexing') {
-        console.log('⏹️ Отмена текущей индексации...');
-        await sdk.projects.cancelIndexing(project.id);
-        await new Promise(resolve => setTimeout(resolve, 2000));
-      }
-      
-      // 3. Запустить новую индексацию
-      console.log('🚀 Запуск индексации...');
-      await sdk.projects.startIndexing(project.id, {
-        forceFull: attempt > 1, // При повторной попытке - полная индексация
-        excludePatterns
-      });
-      
-      // 4. Мониторинг с таймаутом
-      const startTime = Date.now();
-      let lastProgress = 0;
-      
-      while (Date.now() - startTime < timeout) {
-        status = await sdk.projects.getProjectStatus(project.id);
-        
-        if (status.status === 'ready') {
-          console.log('✅ Индексация завершена успешно!');
-          
-          // Получить статистику
-          try {
-            const stats = await sdk.search.getFunctionStats(project.id);
-            console.log(`📈 Статистика: ${stats.stats.totalFunctions} функций найдено`);
-          } catch (error) {
-            console.log('⚠️ Не удалось получить статистику функций');
-          }
-          
-          return project;
-        }
-        
-        if (status.status === 'error') {
-          throw new Error(`Ошибка индексации: ${status.error}`);
-        }
-        
-        // Показать прогресс только если изменился
-        if (status.progress && status.progress !== lastProgress) {
-          lastProgress = status.progress;
-          const processedInfo = status.processedFiles && status.totalFiles 
-            ? ` (${status.processedFiles}/${status.totalFiles} файлов)`
-            : '';
-          console.log(`📊 Прогресс: ${status.progress}%${processedInfo}`);
-          
-          if (status.currentFile) {
-            console.log(`📄 Обрабатывается: ${status.currentFile}`);
-          }
-        }
-        
-        await new Promise(resolve => setTimeout(resolve, 3000));
-      }
-      
-      // Таймаут - отменяем индексацию
-      console.log('⏰ Таймаут индексации, отмена...');
-      await sdk.projects.cancelIndexing(project.id);
-      throw new Error('Превышен таймаут индексации');
-      
-    } catch (error) {
-      console.error(`❌ Ошибка на попытке ${attempt}:`, error.message);
-      
-      if (attempt >= retryAttempts) {
-        throw new Error(`Не удалось проиндексировать проект после ${retryAttempts} попыток: ${error.message}`);
-      }
-      
-      // Ждем перед повторной попыткой
-      await new Promise(resolve => setTimeout(resolve, 5000));
-    }
-  }
-}
-
-// Использование
-const project = await advancedIndexing('/path/to/my-project', {
-  projectName: 'My React App',
-  timeout: 600000,  // 10 минут
-  retryAttempts: 2,
-  excludePatterns: ['node_modules/**', 'dist/**', '*.log']
-});
-```
-
-## 🎯 Интеграция с VS Code Extension
-
-### Базовая интеграция
-
-```javascript
-import * as vscode from 'vscode';
-import { CodeSolverSDK } from 'solver-sdk';
-
-class ProjectIndexer {
-  constructor() {
-    this.sdk = null;
-    this.currentProject = null;
-  }
-  
-  async initialize() {
-    this.sdk = await CodeSolverSDK.create({
-      baseURL: 'http://localhost:3000'
-    });
-  }
-  
-  async indexCurrentWorkspace() {
-    if (!vscode.workspace.workspaceFolders) {
-      vscode.window.showErrorMessage('Нет открытой рабочей области');
-      return;
-    }
-    
-    const workspaceFolder = vscode.workspace.workspaceFolders[0];
-    const projectPath = workspaceFolder.uri.fsPath;
-    const projectName = workspaceFolder.name;
-    
-    return vscode.window.withProgress({
-      location: vscode.ProgressLocation.Notification,
-      title: 'Индексация проекта',
-      cancellable: true
-    }, async (progress, token) => {
-      try {
-        // Создать проект
-        progress.report({ message: 'Создание проекта...' });
-        const project = await this.sdk.projects.findOrCreateProject(projectPath, projectName);
-        this.currentProject = project;
-        
-        // Запустить индексацию
-        progress.report({ message: 'Запуск индексации...' });
-        await this.sdk.projects.startIndexing(project.id);
-        
-        // Мониторинг прогресса
-        while (!token.isCancellationRequested) {
-          const status = await this.sdk.projects.getProjectStatus(project.id);
-          
-          if (status.status === 'ready') {
-            vscode.window.showInformationMessage('✅ Индексация завершена!');
-            break;
-          } else if (status.status === 'error') {
-            throw new Error(status.error);
-          }
-          
-          const progressPercentage = status.progress || 0;
-          const message = status.currentFile 
-            ? `${progressPercentage}% - ${status.currentFile}`
-            : `${progressPercentage}%`;
-            
-          progress.report({ 
-            increment: progressPercentage,
-            message 
-          });
-          
-          await new Promise(resolve => setTimeout(resolve, 2000));
-        }
-        
-        // Отмена по запросу пользователя
-        if (token.isCancellationRequested) {
-          await this.sdk.projects.cancelIndexing(project.id);
-          vscode.window.showWarningMessage('Индексация отменена');
-        }
-        
-      } catch (error) {
-        vscode.window.showErrorMessage(`Ошибка индексации: ${error.message}`);
-      }
-    });
-  }
-  
-  async getReadyProjects() {
-    return await this.sdk.projects.getReadyProjects();
-  }
-}
-
-// Регистрация команд в extension.ts
-export function activate(context: vscode.ExtensionContext) {
-  const indexer = new ProjectIndexer();
-  
-  // Инициализация при активации
-  indexer.initialize();
-  
-  // Команда индексации
-  const indexCommand = vscode.commands.registerCommand(
-    'myExtension.indexProject',
-    () => indexer.indexCurrentWorkspace()
-  );
-  
-  // Команда просмотра проектов
-  const projectsCommand = vscode.commands.registerCommand(
-    'myExtension.showProjects',
-    async () => {
-      const projects = await indexer.getReadyProjects();
-      const items = projects.map(p => ({
-        label: p.name,
-        description: p.path,
-        project: p
-      }));
-      
-      const selected = await vscode.window.showQuickPick(items);
-      if (selected) {
-        vscode.window.showInformationMessage(`Выбран проект: ${selected.project.name}`);
-      }
-    }
-  );
-  
-  context.subscriptions.push(indexCommand, projectsCommand);
-}
-```
-
-### Автоматическая индексация при изменениях
-
-```javascript
-class AutoIndexer {
-  constructor(sdk) {
-    this.sdk = sdk;
-    this.indexingQueue = new Set();
-    this.debounceTimers = new Map();
-  }
-  
-  startWatching() {
-    // Отслеживание изменений файлов
-    vscode.workspace.onDidSaveTextDocument(async (document) => {
-      await this.onFileChanged(document.uri.fsPath);
-    });
-    
-    // Отслеживание создания файлов
-    vscode.workspace.onDidCreateFiles(async (event) => {
-      for (const file of event.files) {
-        await this.onFileChanged(file.fsPath);
-      }
-    });
-    
-    // Отслеживание удаления файлов  
-    vscode.workspace.onDidDeleteFiles(async (event) => {
-      for (const file of event.files) {
-        await this.onFileDeleted(file.fsPath);
-      }
-    });
-  }
-  
-  async onFileChanged(filePath) {
-    const workspaceFolder = vscode.workspace.getWorkspaceFolder(vscode.Uri.file(filePath));
-    if (!workspaceFolder) return;
-    
-    const projectPath = workspaceFolder.uri.fsPath;
-    
-    // Debounce - не чаще раза в 5 секунд для одного проекта
-    if (this.debounceTimers.has(projectPath)) {
-      clearTimeout(this.debounceTimers.get(projectPath));
-    }
-    
-    this.debounceTimers.set(projectPath, setTimeout(async () => {
-      await this.reindexFile(projectPath, filePath);
-      this.debounceTimers.delete(projectPath);
-    }, 5000));
-  }
-  
-  async reindexFile(projectPath, filePath) {
-    try {
-      // Найти проект
-      const project = await this.sdk.projects.findOrCreateProject(projectPath);
-      
-      // Переиндексировать конкретный файл (если поддерживается)
-      const relativePath = path.relative(projectPath, filePath);
-      
-      // Пока используем полную переиндексацию
-      if (!this.indexingQueue.has(project.id)) {
-        this.indexingQueue.add(project.id);
-        
-        await this.sdk.projects.startIndexing(project.id, {
-          forceFull: false  // Инкрементальная индексация
-        });
-        
-        // Ждем завершения
-        while (true) {
-          const status = await this.sdk.projects.getProjectStatus(project.id);
-          if (status.status !== 'indexing') break;
-          await new Promise(resolve => setTimeout(resolve, 1000));
-        }
-        
-        this.indexingQueue.delete(project.id);
-      }
-      
-    } catch (error) {
-      console.error('Ошибка автоиндексации:', error.message);
-    }
-  }
-}
-```
-
-## 📊 Статистика и мониторинг
-
-### Получение детальной статистики
-
-```javascript
-async function getProjectStatistics(projectId) {
-  const sdk = await CodeSolverSDK.create({
-    baseURL: 'http://localhost:3000'
-  });
-  
-  try {
-    // Общая информация о проекте
-    const project = await sdk.projects.getProject(projectId);
-    console.log('📁 Проект:', project);
-    
-    // Статистика функций
-    const functionStats = await sdk.search.getFunctionStats(projectId);
-    console.log('📊 Статистика функций:', functionStats.stats);
-    
-    // Тест поиска для проверки качества индексации
-    const searchTest = await sdk.search.searchCode(projectId, {
-      query: 'function',
-      limit: 5
-    });
-    console.log('🔍 Тестовый поиск:', searchTest.length, 'результатов');
-    
-    const functionSearch = await sdk.search.searchFunctions(projectId, {
-      query: 'main',
-      limit: 3
-    });
-    console.log('🎯 Поиск функций:', functionSearch.resultsCount, 'найдено');
-    
-    return {
-      project,
-      functionStats: functionStats.stats,
-      searchQuality: {
-        basicSearch: searchTest.length,
-        functionSearch: functionSearch.resultsCount
-      }
-    };
-    
-  } catch (error) {
-    console.error('Ошибка получения статистики:', error.message);
-    return null;
-  }
-}
-
-// Использование
-const stats = await getProjectStatistics('12345678-1234-1234-1234-123456789012');
-if (stats) {
-  console.log(`
-📈 Отчет по проекту ${stats.project.name}:
-   • Всего функций: ${stats.functionStats.totalFunctions}
-   • Функции: ${stats.functionStats.functions}
-   • Методы: ${stats.functionStats.methods}
-   • Классы: ${stats.functionStats.classes}
-   • Интерфейсы: ${stats.functionStats.interfaces}
-   • Поиск работает: ${stats.searchQuality.basicSearch > 0 ? '✅' : '❌'}
-   • Поиск функций работает: ${stats.searchQuality.functionSearch > 0 ? '✅' : '❌'}
-  `);
-}
-```
-
-## 🚨 Обработка ошибок
-
-### Типичные ошибки и решения
-
-```javascript
-async function robustIndexing(projectPath, projectName) {
-  const sdk = await CodeSolverSDK.create({
-    baseURL: 'http://localhost:3000'
-  });
-  
-  try {
-    const project = await sdk.projects.findOrCreateProject(projectPath, projectName);
-    await sdk.projects.startIndexing(project.id);
-    
-    // Мониторинг с обработкой ошибок
-    while (true) {
-      try {
-        const status = await sdk.projects.getProjectStatus(project.id);
-        
-        if (status.status === 'ready') {
-          console.log('✅ Успешно завершено');
-          return project;
-        }
-        
-        if (status.status === 'error') {
-          // Обработка различных типов ошибок
-          if (status.error?.includes('timeout')) {
-            console.log('⏰ Ошибка таймаута, повторная попытка...');
-            await sdk.projects.clearIndexingError(project.id);
-            await sdk.projects.startIndexing(project.id, { forceFull: true });
-            continue;
-          }
-          
-          if (status.error?.includes('disk space')) {
-            throw new Error('❌ Недостаточно места на диске');
-          }
-          
-          if (status.error?.includes('permission')) {
-            throw new Error('❌ Нет прав доступа к файлам проекта');
-          }
-          
-          throw new Error(`❌ Ошибка индексации: ${status.error}`);
-        }
-        
-        await new Promise(resolve => setTimeout(resolve, 2000));
-        
-      } catch (networkError) {
-        // Обработка сетевых ошибок
-        if (networkError.code === 'ECONNREFUSED') {
-          throw new Error('❌ Сервер недоступен. Проверьте что бэкенд запущен на http://localhost:3000');
-        }
-        
-        if (networkError.response?.status === 404) {
-          throw new Error('❌ API endpoint не найден. Проверьте версию SDK и бэкенда');
-        }
-        
-        if (networkError.response?.status === 500) {
-          console.log('⚠️ Временная ошибка сервера, повторная попытка через 10 секунд...');
-          await new Promise(resolve => setTimeout(resolve, 10000));
-          continue;
-        }
-        
-        throw networkError;
-      }
-    }
-    
-  } catch (error) {
-    console.error('💥 Критическая ошибка:', error.message);
-    
-    // Попытка очистки
-    try {
-      if (project?.id) {
-        await sdk.projects.cancelIndexing(project.id);
-      }
-    } catch (cleanupError) {
-      console.error('Ошибка очистки:', cleanupError.message);
-    }
-    
-    throw error;
-  }
-}
-```
-
-## 📝 Лучшие практики
-
-### 1. Оптимизация производительности
-
-```javascript
-// ✅ Правильно - исключить ненужные файлы
-const excludePatterns = [
-  'node_modules/**',
-  '.git/**',
-  'dist/**',
-  'build/**',
-  '*.log',
-  '*.tmp',
-  '.cache/**',
-  'coverage/**'
-];
-
-await sdk.projects.startIndexing(project.id, { excludePatterns });
-```
-
-### 2. Управление ресурсами
-
-```javascript
-// ✅ Правильно - одно подключение на приложение
-class IndexingManager {
-  constructor() {
-    this.sdk = null;
-    this.activeIndexing = new Map();
-  }
-  
-  async initialize() {
-    if (!this.sdk) {
-      this.sdk = await CodeSolverSDK.create({
-        baseURL: 'http://localhost:3000'
-      });
-    }
-  }
-  
-  async indexProject(projectPath) {
-    // Предотвращение параллельной индексации одного проекта
-    if (this.activeIndexing.has(projectPath)) {
-      throw new Error('Проект уже индексируется');
-    }
-    
-    this.activeIndexing.set(projectPath, true);
-    
-    try {
-      // ... логика индексации
-    } finally {
-      this.activeIndexing.delete(projectPath);
-    }
-  }
-}
-```
-
-### 3. Пользовательский интерфейс
-
-```javascript
-// ✅ Правильно - информативная обратная связь
-async function indexWithUI(projectPath) {
-  const statusDiv = document.getElementById('indexing-status');
-  const progressBar = document.getElementById('progress-bar');
-  
-  try {
-    statusDiv.textContent = '🚀 Запуск индексации...';
-    
-    const project = await sdk.projects.findOrCreateProject(projectPath);
-    await sdk.projects.startIndexing(project.id);
-    
-    while (true) {
-      const status = await sdk.projects.getProjectStatus(project.id);
-      
-      if (status.status === 'ready') {
-        statusDiv.textContent = '✅ Индексация завершена!';
-        progressBar.style.width = '100%';
-        break;
-      }
-      
-      if (status.progress) {
-        progressBar.style.width = `${status.progress}%`;
-        statusDiv.textContent = `📊 ${status.progress}% - ${status.currentFile || 'Обработка...'}`;
-      }
-      
-      await new Promise(resolve => setTimeout(resolve, 1000));
-    }
-    
-  } catch (error) {
-    statusDiv.textContent = `❌ Ошибка: ${error.message}`;
-    progressBar.style.backgroundColor = 'red';
-  }
-}
-```
-
-## 🎯 Заключение
-
-Индексация - ключевая функция для работы с поиском и AI анализом кода. Основные шаги:
-
-1. **Создание проекта** - `findOrCreateProject()`
-2. **Запуск индексации** - `startIndexing()`  
-3. **Мониторинг прогресса** - `getProjectStatus()`
-4. **Использование результатов** - поиск функций и кода
-
-**Помните:**
-- Всегда обрабатывайте ошибки
-- Показывайте прогресс пользователю
-- Исключайте ненужные файлы
-- Тестируйте результаты индексации