solver-sdk 2.3.0 → 2.6.0

package/docs/indexing/INDEXING.md

@@ -1,231 +1,436 @@
-# Индексация проектов
+# Индексация проектов v2.5.0
 
-Это руководство описывает, как использовать SDK для индексации проектов и отдельных файлов.
+Руководство по индексации проектов в AI Solver SDK v2.5.0.
 
 ## Инициализация SDK
 
-Прежде чем использовать функции индексации, необходимо инициализировать SDK с указанием API ключа:
+```javascript
+import { CodeSolverSDK } from '@ai-solver/sdk';
 
-```typescript
-import { CodeSolverSDK } from 'solver-sdk';
-
-const sdk = new CodeSolverSDK({
-  baseURL: 'https://api.example.com',
-  apiKey: 'ваш_api_ключ', // API ключ обязателен для авторизации WebSocket соединений
+const sdk = CodeSolverSDK.create({
+  baseURL: 'http://localhost:3000',
+  apiKey: 'dev_sk_test_12345678',
+  autoConnect: false
 });
 ```
 
-## Индексация проекта
-
-### Запуск индексации
-
-Для запуска индексации проекта используйте метод `indexProject` или его псевдоним `startIndexing`:
-
-```typescript
-// Полная индексация проекта
-await sdk.projects.indexProject('идентификатор_проекта', {
-  indexingMode: 'full'
-});
+## Основной workflow индексации
 
-// Инкрементальная индексация (только изменившиеся файлы)
-await sdk.projects.indexProject('идентификатор_проекта', {
-  indexingMode: 'incremental'
-});
+### 1. Создание проекта
 
-// Автоматический выбор режима индексации (рекомендуется)
-await sdk.projects.indexProject('идентификатор_проекта', {
-  indexingMode: 'auto'
+```javascript
+const project = await sdk.projects.create({
+  name: 'My Code Project',
+  path: '/path/to/project',
+  description: 'Project for AI analysis'
 });
 
-// Псевдоним startIndexing (работает аналогично indexProject)
-await sdk.projects.startIndexing('идентификатор_проекта', {
-  indexingMode: 'auto'
-});
+console.log('Project created:', project.id);
 ```
 
-### Режимы индексации
+### 2. Запуск индексации
+
+```javascript
+// Запуск индексации проекта
+await sdk.projects.startIndexing(project.id);
 
-SDK поддерживает следующие режимы индексации:
+console.log('Indexing started for project:', project.id);
+```
 
-- **full** - полная переиндексация всех файлов проекта
-- **incremental** - индексация только изменившихся файлов (более быстрая)
-- **auto** - автоматический выбор режима на основе метаданных проекта
+### 3. Проверка статуса
 
-Вы также можете использовать флаг `forceFull` для принудительной полной индексации:
+```javascript
+// Получение статуса индексации
+const status = await sdk.projects.getIndexingStatus(project.id);
 
-```typescript
-await sdk.projects.indexProject('идентификатор_проекта', {
-  forceFull: true
-});
+console.log('Indexing status:', status.indexStatus);
+console.log('Progress:', status.indexingProgress);
+console.log('Files indexed:', status.filesIndexed);
 ```
 
-### Фильтрация файлов
+## WebSocket мониторинг индексации
 
-Можно указать шаблоны включения и исключения файлов:
+### Подключение и события
+
+```javascript
+// Подключение к projects WebSocket
+await sdk.projects.connectWebSocket();
 
-```typescript
-await sdk.projects.indexProject('идентификатор_проекта', {
-  indexingMode: 'auto',
-  includePatterns: ['**/*.js', '**/*.ts', '**/*.jsx', '**/*.tsx'],
-  excludePatterns: ['**/node_modules/**', '**/dist/**', '**/build/**']
+// Отслеживание прогресса
+sdk.projects.onIndexingProgress((data) => {
+  console.log(`Progress: ${data.percentage}%`);
+  console.log(`Files: ${data.processedFiles}/${data.totalFiles}`);
+  console.log(`Current file: ${data.currentFile}`);
+  console.log(`Speed: ${data.filesPerSecond} files/sec`);
 });
-```
 
-## Обновление индекса отдельных файлов
+// Завершение индексации
+sdk.projects.onIndexingComplete((data) => {
+  console.log('✅ Indexing completed!');
+  console.log('Project ID:', data.projectId);
+  console.log('Total files:', data.totalFiles);
+  console.log('Duration:', data.duration + 'ms');
+  console.log('Success:', data.success);
+  
+  // Отключение WebSocket
+  sdk.projects.disconnectWebSocket();
+});
 
-Для индексации одного файла используйте метод `updateFileIndex`:
+// Ошибки индексации
+sdk.projects.onIndexingError((error) => {
+  console.error('❌ Indexing error:', error.message);
+  console.error('Project:', error.projectId);
+  console.error('File:', error.fileName);
+  
+  sdk.projects.disconnectWebSocket();
+});
+```
 
-```typescript
-// Индексация файла с чтением его содержимого с диска
-await sdk.projects.updateFileIndex(
-  'идентификатор_проекта',
-  'путь/к/файлу.js'
-);
+## Полный пример с обработкой ошибок
 
-// Индексация с передачей содержимого файла
-await sdk.projects.updateFileIndex(
-  'идентификатор_проекта',
-  'путь/к/файлу.js',
-  {
-    content: 'содержимое файла',
-    force: true // Принудительная индексация, даже если файл не изменился
+```javascript
+async function indexProjectWithMonitoring(projectPath, projectName) {
+  const sdk = CodeSolverSDK.create({
+    baseURL: 'http://localhost:3000',
+    apiKey: process.env.AI_SOLVER_API_KEY,
+    autoConnect: false
+  });
+  
+  try {
+    console.log('🔍 Creating project...');
+    
+    // 1. Создание проекта
+    const project = await sdk.projects.create({
+      name: projectName,
+      path: projectPath,
+      description: `AI analysis project for ${projectName}`
+    });
+    
+    console.log('✅ Project created:', project.id);
+    
+    // 2. Подключение к WebSocket для мониторинга
+    console.log('🔌 Connecting to WebSocket...');
+    await sdk.projects.connectWebSocket();
+    
+    // 3. Настройка обработчиков событий
+    let indexingComplete = false;
+    
+    sdk.projects.onIndexingProgress((data) => {
+      const progress = Math.round(data.percentage);
+      console.log(`📊 [${progress}%] ${data.currentFile || 'Processing...'}`);
+    });
+    
+    sdk.projects.onIndexingComplete((data) => {
+      console.log('🎉 Indexing completed successfully!');
+      console.log(`📈 Statistics:`);
+      console.log(`   - Total files: ${data.totalFiles}`);
+      console.log(`   - Duration: ${data.duration}ms`);
+      console.log(`   - Success: ${data.success}`);
+      
+      indexingComplete = true;
+      sdk.projects.disconnectWebSocket();
+    });
+    
+    sdk.projects.onIndexingError((error) => {
+      console.error('💥 Indexing failed:', error.message);
+      indexingComplete = true;
+      sdk.projects.disconnectWebSocket();
+    });
+    
+    // 4. Запуск индексации
+    console.log('🚀 Starting indexing...');
+    await sdk.projects.startIndexing(project.id);
+    
+    // 5. Ожидание завершения
+    while (!indexingComplete) {
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    }
+    
+    // 6. Проверка финального статуса
+    const finalStatus = await sdk.projects.getIndexingStatus(project.id);
+    console.log('📋 Final status:', finalStatus);
+    
+    return {
+      success: true,
+      project: project,
+      status: finalStatus
+    };
+    
+  } catch (error) {
+    console.error('❌ Indexing workflow failed:', error.message);
+    
+    // Очистка ресурсов
+    try {
+      await sdk.projects.disconnectWebSocket();
+    } catch (cleanupError) {
+      console.warn('⚠️ Cleanup warning:', cleanupError.message);
+    }
+    
+    return {
+      success: false,
+      error: error.message
+    };
   }
-);
+}
 
-// С дополнительными опциями
-await sdk.projects.updateFileIndex(
-  'идентификатор_проекта',
-  'путь/к/файлу.ts',
-  {
-    content: 'содержимое файла',
-    language: 'typescript', // Явное указание языка
-    updateDependencies: true // Обновление зависимостей после индексации
-  }
+// Использование
+const result = await indexProjectWithMonitoring(
+  '/path/to/my/project',
+  'My AI Project'
 );
-```
-
-## Работа с новыми проектами
-
-### Создание и индексация проекта
 
-```typescript
-// Создание проекта и немедленная индексация
-const result = await sdk.projects.createAndIndexProject('/путь/к/проекту', {
-  name: 'Название проекта',
-  indexingMode: 'full',
-  excludePatterns: ['**/node_modules/**', '**/dist/**']
-});
+if (result.success) {
+  console.log('🎯 Project ready for AI analysis!');
+} else {
+  console.error('💔 Indexing failed:', result.error);
+}
+```
 
-console.log(`Проект создан с ID: ${result.projectId}`);
-console.log(`Статус индексации: ${result.indexingStatus}`);
+## API Endpoints для индексации
+
+### HTTP API
+
+| Endpoint | Method | Описание |
+|----------|--------|----------|
+| `/api/v1/projects` | POST | Создание проекта |
+| `/api/v1/projects/:id` | GET | Получение проекта |
+| `/api/v1/projects` | GET | Список проектов |
+| `/api/v1/projects/:id/index` | POST | Запуск индексации |
+| `/api/v1/projects/:id/index/status` | GET | Статус индексации |
+
+### WebSocket Events
+
+| Event | Namespace | Описание |
+|-------|-----------|----------|
+| `indexing_progress` | `/projects` | Прогресс индексации |
+| `indexing_complete` | `/projects` | Завершение индексации |
+| `indexing_error` | `/projects` | Ошибка индексации |
+
+## Структуры данных
+
+### Project Object
+
+```javascript
+{
+  id: "proj_abc123",
+  name: "My Project",
+  path: "/path/to/project",
+  description: "Project description",
+  indexStatus: "completed", // pending, indexing, completed, failed
+  indexingProgress: 100,
+  filesIndexed: 150,
+  lastIndexed: "2025-06-28T12:00:00Z",
+  createdAt: "2025-06-28T11:00:00Z",
+  updatedAt: "2025-06-28T12:00:00Z"
+}
 ```
 
-### Поиск или создание проекта
+### Indexing Status
+
+```javascript
+{
+  projectId: "proj_abc123",
+  indexStatus: "completed",
+  indexingProgress: 100,
+  filesIndexed: 150,
+  totalFiles: 150,
+  lastUpdated: "2025-06-28T12:00:00Z",
+  startedAt: "2025-06-28T11:45:00Z",
+  completedAt: "2025-06-28T12:00:00Z"
+}
+```
 
-```typescript
-// Найти существующий проект или создать новый
-const project = await sdk.projects.getOrCreateProject('/путь/к/проекту', 'Название проекта');
-console.log(`ID проекта: ${project.id}`);
+### Progress Event
+
+```javascript
+{
+  projectId: "proj_abc123",
+  percentage: 75,
+  processedFiles: 112,
+  totalFiles: 150,
+  currentFile: "src/components/App.tsx",
+  status: "indexing",
+  filesPerSecond: 8.5,
+  estimatedTimeRemaining: 4500
+}
+```
 
-// После получения проекта можно запустить индексацию
-await sdk.projects.indexProject(project.id, {
-  indexingMode: 'auto'
-});
+### Complete Event
+
+```javascript
+{
+  projectId: "proj_abc123",
+  totalFiles: 150,
+  duration: 18750,
+  success: true,
+  errors: [],
+  statistics: {
+    byLanguage: {
+      "typescript": 45,
+      "javascript": 38,
+      "css": 12,
+      "html": 8,
+      "json": 5,
+      "markdown": 2
+    },
+    totalLines: 12450,
+    totalSize: 1024000
+  }
+}
 ```
 
-## Управление индексацией
+## Обработка ошибок
 
-### Проверка статуса индексации
+### Типичные ошибки индексации
 
-```typescript
-// Получение текущего статуса индексации
-const status = await sdk.projects.getIndexingStatus('идентификатор_проекта');
-console.log(`Статус: ${status.status}`);
-console.log(`Количество файлов: ${status.fileCount}`);
-console.log(`Статистика по языкам:`, status.languageStats);
-```
+```javascript
+// Проект не найден
+{
+  status: 404,
+  code: 'PROJECT_NOT_FOUND',
+  message: 'Project with ID "proj_123" not found'
+}
 
-### Отмена индексации
+// Индексация уже запущена
+{
+  status: 409,
+  code: 'INDEXING_IN_PROGRESS',
+  message: 'Indexing is already in progress for this project'
+}
 
-```typescript
-// Отмена текущей индексации
-await sdk.projects.cancelIndexing('идентификатор_проекта');
+// Ошибка доступа к файлам
+{
+  status: 500,
+  code: 'FILESYSTEM_ERROR',
+  message: 'Cannot access project files',
+  details: {
+    path: '/path/to/project',
+    error: 'Permission denied'
+  }
+}
 ```
 
-### Очистка ошибок индексации
-
-```typescript
-// Очистка ошибки, если индексация завершилась с ошибкой
-await sdk.projects.clearIndexingError('идентификатор_проекта');
+### Стратегия retry
+
+```javascript
+async function retryableIndexing(projectId, maxRetries = 3) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      await sdk.projects.startIndexing(projectId);
+      console.log('✅ Indexing started successfully');
+      return true;
+      
+    } catch (error) {
+      console.warn(`⚠️ Attempt ${attempt} failed:`, error.message);
+      
+      // Не повторяем для клиентских ошибок
+      if (error.status >= 400 && error.status < 500) {
+        throw error;
+      }
+      
+      // Последняя попытка
+      if (attempt === maxRetries) {
+        throw error;
+      }
+      
+      // Задержка между попытками
+      const delay = Math.pow(2, attempt) * 1000;
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+}
 ```
 
-## Отслеживание индексации через WebSocket
+## Диагностика проблем
 
-SDK поддерживает отслеживание процесса индексации в реальном времени через WebSocket:
+### Проверка доступности API
 
-```typescript
-// Подключение к WebSocket
-await sdk.projects.connectWebSocket();
+```javascript
+// Проверка endpoints для индексации
+const diagnostics = await sdk.diagnoseAPI();
 
-// Подписка на события индексации отдельных файлов
-sdk.projects.on('file_indexed', (data) => {
-  console.log(`Файл индексирован: ${data.file.path}`);
-  console.log(`Язык: ${data.file.language}`);
-  console.log(`Тип изменения: ${data.file.changeType}`);
-});
+const indexingEndpoints = [
+  '/api/v1/projects',
+  '/api/v1/projects/:id/index'
+];
 
-// Подписка на событие завершения индексации
-sdk.projects.on('indexing_complete', (data) => {
-  console.log(`Индексация завершена для проекта ${data.projectId}`);
-  console.log(`Всего файлов: ${data.stats.totalFiles}`);
-  console.log(`Проиндексировано: ${data.stats.indexed}`);
-  console.log(`Ошибок: ${data.stats.failed}`);
-  console.log(`Время индексации: ${data.stats.time}мс`);
+indexingEndpoints.forEach(endpoint => {
+  const status = diagnostics[endpoint];
+  if (status?.success) {
+    console.log(`✅ ${endpoint} - OK`);
+  } else {
+    console.error(`❌ ${endpoint} - ${status?.error || 'Failed'}`);
+  }
 });
-
-// Отключение от WebSocket после завершения работы
-await sdk.projects.disconnectWebSocket();
 ```
 
-## Обработка ошибок
+### WebSocket диагностика
 
-```typescript
-try {
-  await sdk.projects.indexProject('идентификатор_проекта', {
-    indexingMode: 'full'
-  });
-} catch (error) {
-  if (error.message.includes('не найден')) {
-    console.error('Проект не найден');
-  } else if (error.message.includes('forbidden')) {
-    console.error('Ошибка авторизации. Проверьте API ключ');
-  } else {
-    console.error(`Ошибка индексации: ${error.message}`);
-  }
+```javascript
+// Проверка WebSocket для projects
+const wsStatus = await sdk.diagnoseWebSocket();
+
+if (wsStatus.projects?.connected) {
+  console.log('✅ Projects WebSocket - Connected');
+} else {
+  console.error('❌ Projects WebSocket - Disconnected');
+  console.error('Error:', wsStatus.projects?.error);
 }
 ```
 
-## Авторизация WebSocket
+## Рекомендации по производительности
+
+### 1. Используйте WebSocket мониторинг
+
+```javascript
+// ✅ Правильно - с WebSocket
+await sdk.projects.connectWebSocket();
+sdk.projects.onIndexingProgress(handleProgress);
+await sdk.projects.startIndexing(projectId);
+
+// ❌ Неэффективно - polling
+await sdk.projects.startIndexing(projectId);
+while (true) {
+  const status = await sdk.projects.getIndexingStatus(projectId);
+  if (status.indexStatus === 'completed') break;
+  await new Promise(resolve => setTimeout(resolve, 5000));
+}
+```
 
-Начиная с версии 1.7.7, SDK автоматически добавляет API ключ в качестве параметра `authToken` при подключении WebSocket, что обеспечивает корректную авторизацию для всех операций через WebSocket (индексация, рассуждения и т.д.).
+### 2. Правильно управляйте WebSocket
 
-Для корректной работы WebSocket соединений:
-1. **Обязательно указывайте `apiKey` при инициализации SDK**
-2. Подключайтесь к WebSocket перед использованием событий
-3. Отключайтесь от WebSocket после завершения работы
+```javascript
+// ✅ Отключайтесь после завершения
+sdk.projects.onIndexingComplete(() => {
+  sdk.projects.disconnectWebSocket();
+});
 
-```typescript
-// Корректная инициализация с apiKey
-const sdk = new CodeSolverSDK({
-  baseURL: 'https://api.example.com',
-  apiKey: 'ваш_api_ключ' // Обязательно для WebSocket авторизации
+// ✅ Отключайтесь при ошибках
+sdk.projects.onIndexingError(() => {
+  sdk.projects.disconnectWebSocket();
 });
+```
 
-// Подключение
-await sdk.projects.connectWebSocket();
+### 3. Обрабатывайте большие проекты
+
+```javascript
+// Для больших проектов показывайте детальный прогресс
+sdk.projects.onIndexingProgress((data) => {
+  const { percentage, currentFile, filesPerSecond } = data;
+  
+  // Обновление UI
+  updateProgressBar(percentage);
+  updateCurrentFile(currentFile);
+  updateSpeed(filesPerSecond);
+  
+  // Оценка времени
+  const remaining = (100 - percentage) / filesPerSecond;
+  updateETA(remaining);
+});
+```
 
-// Использование WebSocket...
+---
 
-// Отключение
-await sdk.projects.disconnectWebSocket();
-``` 
+**Документация индексации для SDK v2.5.0**  
+**Совместимость:** AI Solver Backend v1.0.0  
+**Обновлено:** 28 июня 2025 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solver-sdk",
-  "version": "2.3.0",
+  "version": "2.6.0",
   "description": "SDK для интеграции с Code Solver Backend API",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",