solver-sdk 1.7.2 → 1.7.3

package/docs/WEBSOCKET_EVENTS.md

@@ -0,0 +1,183 @@
+# Справочник WebSocket событий SDK
+
+Этот документ содержит полный список WebSocket событий, используемых в SDK версии 1.7.2.
+
+## Содержание
+
+- [Типы событий](#типы-событий)
+  - [События рассуждений и сессий](#события-рассуждений-и-сессий)
+  - [События контекста](#события-контекста)
+  - [События чата и мышления](#события-чата-и-мышления)
+  - [События разработки и тестирования](#события-разработки-и-тестирования)
+  - [События соединения](#события-соединения)
+  - [События индексации](#события-индексации)
+  - [События зависимостей](#события-зависимостей)
+- [Использование событий](#использование-событий)
+  - [Низкоуровневое API](#низкоуровневое-api)
+  - [Высокоуровневое API](#высокоуровневое-api)
+- [Диагностика ошибок](#диагностика-ошибок)
+
+## Типы событий
+
+### События рассуждений и сессий
+
+| Константа SDK | Строковое значение | Описание | Данные |
+|---------------|-------------------|----------|--------|
+| `REASONING_CREATED` | `reasoning:created` | Создано новое рассуждение | `{ reasoningId: string, metadata?: object }` |
+| `JOINED_REASONING` | `joined_reasoning` | Клиент присоединился к рассуждению | `{ reasoningId: string, success: boolean }` |
+| `JOIN_REASONING` | `join_reasoning` | Запрос на присоединение к рассуждению | `{ reasoningId: string }` |
+| `JOIN_RESPONSE` | `join_response` | Ответ на запрос присоединения | `{ success: boolean, reasoningId: string, error?: string }` |
+| `JOIN` | `join` | Запрос на присоединение к пространству имен | `{ namespace: string }` |
+| `JOINED` | `joined` | Успешное присоединение к пространству имен | `{ namespace: string, socketId: string }` |
+| `REASONING_STATUS_UPDATE` | `reasoning_status_update` | Обновление статуса рассуждения | `{ reasoningId: string, status: string }` |
+| `START_REASONING` | `start_reasoning` | Запрос на начало рассуждения | `{ reasoningId: string }` |
+| `REASONING_STARTED` | `reasoning_started` | Рассуждение начато | `{ reasoningId: string, startTime: string }` |
+
+### События контекста
+
+| Константа SDK | Строковое значение | Описание | Данные |
+|---------------|-------------------|----------|--------|
+| `UPDATE_CONTEXT_OPTIONS` | `update_context_options` | Обновление опций контекста | `{ reasoningId: string, options: ContextOptions }` |
+| `ESTIMATE_CONTEXT` | `estimate_context` | Запрос на оценку контекста | `{ reasoningId: string, projectId: string }` |
+| `CONTEXT_OPTIONS_UPDATED` | `context_options_updated` | Опции контекста обновлены | `{ reasoningId: string, options: ContextOptions }` |
+| `CONTEXT_ESTIMATION` | `context_estimation` | Результат оценки контекста | `{ reasoningId: string, estimation: ContextEstimation }` |
+| `SET_PROJECT_CONTEXT` | `set_project_context` | Установка контекста проекта | `{ reasoningId: string, projectId: string }` |
+| `PROJECT_CONTEXT_SET` | `project_context_set` | Контекст проекта установлен | `{ reasoningId: string, projectId: string, success: boolean }` |
+
+### События чата и мышления
+
+| Константа SDK | Строковое значение | Описание | Данные |
+|---------------|-------------------|----------|--------|
+| `CHAT_REQUEST` | `chat_request` | Запрос на чат | `{ reasoningId: string, messages: Message[] }` |
+| `CHAT_STARTED` | `chat_started` | Начало обработки запроса чата | `{ reasoningId: string, requestId: string }` |
+| `MESSAGE_START` | `message_start` | Начало сообщения от модели | `{ model: string, type: string, id: string }` |
+| `CONTENT_BLOCK_START` | `content_block_start` | Начало блока контента | `{ index: number, type: string, id: string }` |
+| `THINKING_DELTA` | `thinking_delta` | Фрагмент мышления | `{ text: string, index: number }` |
+| `THINKING_BLOCK_DELTA` | `thinking_block_delta` | Дельта блока мышления | `{ delta: string, index: number }` |
+| `TEXT_DELTA` | `text_delta` | Фрагмент текстового ответа | `{ text: string, index: number }` |
+| `CONTENT_BLOCK_DELTA` | `content_block_delta` | Общая дельта блока контента | `{ delta: string, index: number, type: string }` |
+| `CONTENT_BLOCK_STOP` | `content_block_stop` | Завершение блока контента | `{ index: number, type: string, id: string }` |
+| `MESSAGE_STOP` | `message_stop` | Завершение сообщения | `{ type: string, id: string }` |
+| `CHAT_COMPLETE` | `chat_complete` | Завершение чата | `{ reasoningId: string, requestId: string }` |
+
+### События разработки и тестирования
+
+| Константа SDK | Строковое значение | Описание | Данные |
+|---------------|-------------------|----------|--------|
+| `TYPESCRIPT_ERRORS` | `typescript_errors` | Запрос на получение ошибок TypeScript | `{ reasoningId: string, projectId: string, files: string[] }` |
+| `TYPESCRIPT_ERRORS_RECEIVED` | `typescript_errors_received` | Получены ошибки TypeScript | `{ reasoningId: string, errors: TypeScriptError[] }` |
+| `CREATE_TEST_MODULES` | `create_test_modules` | Запрос на создание тестовых модулей | `{ reasoningId: string, files: string[] }` |
+| `TEST_MODULES_CREATED` | `test_modules_created` | Тестовые модули созданы | `{ reasoningId: string, modules: TestModule[] }` |
+| `ANALYZE_CODE` | `analyze_code` | Запрос на анализ кода | `{ reasoningId: string, code: string, language: string }` |
+| `CODE_ANALYSIS` | `code_analysis` | Результат анализа кода | `{ reasoningId: string, analysis: CodeAnalysis }` |
+
+### События соединения
+
+| Константа SDK | Строковое значение | Описание | Данные |
+|---------------|-------------------|----------|--------|
+| `AUTHENTICATE` | `authenticate` | Аутентификация клиента | `{ apiKey: string }` |
+| `AUTHENTICATION_RESULT` | `authentication_result` | Результат аутентификации | `{ success: boolean, error?: string }` |
+| `CONNECTION_PING` | `connection_ping` | Проверка активности соединения | `{ timestamp: number, id: string }` |
+| `CONNECTION_PONG` | `connection_pong` | Ответ на проверку соединения | `{ timestamp: number, id: string, serverTime: number }` |
+| `RECONNECT_TOKEN` | `reconnect_token` | Токен для переподключения | `{ token: string, namespace: string }` |
+| `DISCONNECT` | `disconnect` | Отключение от сервера | `{ reason: string }` |
+| `ERROR` | `error` | Ошибка соединения | `{ message: string, code?: string, details?: any }` |
+| `CONNECTION_TIMEOUT` | `connection_timeout` | Таймаут соединения | `{ namespace: string, lastPingTime: number }` |
+
+### События индексации
+
+| Константа SDK | Строковое значение | Описание | Данные |
+|---------------|-------------------|----------|--------|
+| `INDEXING_START` | `indexing_start` | Начало процесса индексации | `{ projectId: string }` |
+| `INDEXING_PROGRESS` | `indexing_progress` | Обновление прогресса индексации | `{ projectId: string, totalFiles: number, indexedFiles: number, progress: number }` |
+| `INDEXING_COMPLETE` | `indexing_complete` | Завершение индексации | `{ projectId: string, totalFiles: number, indexedFiles: number }` |
+| `INDEXING_ERROR` | `indexing_error` | Ошибка при индексации | `{ projectId: string, message: string }` |
+| `FILE_INDEXED` | `file_indexed` | Отдельный файл проиндексирован | `{ projectId: string, filePath: string, fileIndex: object }` |
+| `FILE_INDEX_ERROR` | `file_index_error` | Ошибка при индексации файла | `{ projectId: string, filePath: string, message: string }` |
+
+### События зависимостей
+
+| Константа SDK | Строковое значение | Описание | Данные |
+|---------------|-------------------|----------|--------|
+| `DEPENDENCY_UPDATE` | `dependency_update` | Обновление зависимостей | `{ projectId: string, files: string[], type: string }` |
+| `DEPENDENCY_ANALYSIS` | `dependency_analysis` | Анализ зависимостей | `{ projectId: string, analysis: DependencyAnalysis }` |
+| `DEPENDENCY_GRAPH_READY` | `dependency_graph_ready` | Граф зависимостей готов | `{ projectId: string, nodes: number, edges: number }` |
+| `DEPENDENCY_CYCLE_FOUND` | `dependency_cycle_found` | Найден цикл в зависимостях | `{ projectId: string, cycle: string[] }` |
+
+## Использование событий
+
+### Низкоуровневое API
+
+Для работы с событиями через низкоуровневое API WebSocket клиента:
+
+```javascript
+const wsClient = sdk.getWebSocketClient();
+
+// Подписка на событие
+wsClient.on('thinking_delta', (data) => {
+  console.log('Получен фрагмент мышления:', data.text);
+});
+
+// Отправка события
+wsClient.emit('join_reasoning', { reasoningId: 'my-reasoning-id' });
+
+// Отправка события с ожиданием ответа
+const response = await wsClient.emitWithResponse('join_reasoning', 
+  { reasoningId: 'my-reasoning-id' },
+  'join_response',  // Тип ожидаемого ответа
+  10000             // Таймаут в миллисекундах
+);
+```
+
+### Высокоуровневое API
+
+Для работы с событиями через высокоуровневое API модулей SDK (версия 1.7.2+):
+
+```javascript
+// Чат и рассуждения
+await sdk.chat.connectWebSocket();
+sdk.chat.on('thinking_delta', (data) => {
+  console.log('Фрагмент мышления:', data.text);
+});
+
+// Зависимости
+await sdk.dependencies.connectWebSocket(projectId);
+sdk.dependencies.on('dependency_update', (data) => {
+  console.log('Обновление зависимостей:', data);
+});
+
+// Проекты и индексация
+await sdk.projects.connectWebSocket();
+sdk.projects.on('indexing_progress', (data) => {
+  console.log('Прогресс индексации:', data.progress);
+});
+```
+
+## Диагностика ошибок
+
+Возможные причины проблем с событиями WebSocket:
+
+1. **Неверный формат события** - убедитесь, что отправляете корректные данные в соответствии с ожидаемой структурой.
+2. **Неправильный порядок событий** - некоторые события должны следовать в определенном порядке (например, `authenticate` → `join` → `join_reasoning`).
+3. **Таймауты** - события с ожиданием ответа могут завершиться ошибкой по таймауту.
+4. **Разрыв соединения** - проверьте стабильность соединения с помощью механизма ping/pong.
+
+Для диагностики используйте:
+
+```javascript
+// Включение расширенного логирования
+const sdk = new CodeSolverSDK({
+  websocket: {
+    debug: true
+  }
+});
+
+// Диагностика соединения
+const diagnostics = sdk.getWebSocketClient().diagnoseConnection(WebSocketNamespace.REASONING);
+console.log('Диагностика:', diagnostics);
+
+// Мониторинг всех событий
+sdk.getWebSocketClient().onAny((eventName, ...args) => {
+  console.log(`Событие ${eventName}:`, args);
+});
+``` 

package/docs/indexing/INDEXING.md

@@ -0,0 +1,401 @@
+# Индексация проектов в Solver SDK
+
+Данный документ описывает процесс индексации проектов через SDK и отслеживания этого процесса с помощью WebSocket соединений.
+
+## Содержание
+
+- [Введение](#введение)
+- [API для индексации](#api-для-индексации)
+- [Инкрементальная индексация](#инкрементальная-индексация)
+- [Отслеживание процесса индексации](#отслеживание-процесса-индексации)
+- [События WebSocket](#события-websocket)
+- [Обработка ошибок](#обработка-ошибок)
+- [Примеры использования](#примеры-использования)
+
+## Введение
+
+Индексация проекта - это процесс сканирования и анализа файлов проекта для дальнейшего поиска и обработки информации. Solver SDK предоставляет набор методов для управления индексацией проектов и отслеживания этого процесса.
+
+## API для индексации
+
+### Основные методы
+
+| Метод | Описание |
+|-------|----------|
+| `sdk.projects.indexProject(projectId, options)` | Запускает индексацию проекта |
+| `sdk.projects.stopIndexing(projectId)` | Останавливает индексацию проекта |
+| `sdk.projects.getIndexingStatus(projectId)` | Получает текущий статус индексации |
+| `sdk.projects.updateFileIndex(projectId, filePath, options)` | Обновляет индекс конкретного файла |
+
+### Пример использования API
+
+```javascript
+// Запуск индексации
+const result = await sdk.projects.indexProject(projectId, {
+  forceFull: false, // true для принудительной полной переиндексации
+  includePatterns: ['**/*.js', '**/*.ts'], // glob паттерны для включения файлов
+  excludePatterns: ['**/node_modules/**'] // glob паттерны для исключения файлов
+});
+console.log('Индексация запущена. Задача:', result.taskId);
+
+// Получение статуса индексации
+const status = await sdk.projects.getIndexingStatus(projectId);
+console.log(`Статус: ${status.status}, прогресс: ${status.progress}%`);
+
+// Остановка индексации
+await sdk.projects.stopIndexing(projectId);
+console.log('Индексация остановлена');
+```
+
+## Инкрементальная индексация
+
+В SDK версии 1.7.2 добавлена поддержка инкрементальной индексации отдельных файлов, что позволяет обновлять только изменившиеся файлы без необходимости переиндексации всего проекта.
+
+### Обновление индекса отдельного файла
+
+```javascript
+// Обновление индекса файла с передачей содержимого
+const result = await sdk.projects.updateFileIndex(
+  projectId,
+  'src/components/App.js',
+  {
+    content: 'console.log("Hello World");', // содержимое файла
+    force: false // true для принудительного обновления
+  }
+);
+
+console.log(`Файл ${result.filePath} успешно проиндексирован`);
+console.log(`Метаданные файла:`, result.fileIndex);
+
+// Альтернативный вариант через ContextApi
+await sdk.context.updateFileIndex(
+  projectId,
+  'src/components/App.js',
+  'console.log("Hello World");',
+  false // force flag
+);
+```
+
+### Инкрементальная индексация из файловой системы
+
+```javascript
+// Обновление индекса без передачи содержимого
+// SDK прочитает файл с диска
+const result = await sdk.projects.updateFileIndex(projectId, 'src/components/App.js');
+
+console.log(`Файл ${result.filePath} успешно проиндексирован`);
+```
+
+### Пакетное обновление нескольких файлов
+
+```javascript
+// Обновление нескольких файлов
+const filesToUpdate = [
+  { path: 'src/components/App.js' },
+  { path: 'src/utils/helpers.js', content: 'export function helper() {}' }
+];
+
+const results = await Promise.all(
+  filesToUpdate.map(file => 
+    sdk.projects.updateFileIndex(projectId, file.path, { content: file.content })
+  )
+);
+
+console.log(`Обновлено ${results.length} файлов`);
+```
+
+## Отслеживание процесса индексации
+
+Для отслеживания процесса индексации в реальном времени используется WebSocket соединение. SDK предоставляет методы для подключения к серверу и получения событий о ходе индексации.
+
+### Подключение к WebSocket (версия 1.7.2)
+
+```javascript
+// Прямое подключение к пространству имен индексации
+await sdk.projects.connectWebSocket();
+
+// Проверка подключения
+if (sdk.projects.isWebSocketConnected()) {
+  console.log('Успешно подключено к WebSocket серверу');
+} else {
+  console.error('Не удалось подключиться к WebSocket серверу');
+}
+```
+
+### Установка обработчиков событий
+
+```javascript
+// Установка обработчиков событий
+sdk.projects.on('indexing_start', (data) => {
+  console.log(`Индексация началась для проекта: ${data.projectId}`);
+});
+
+sdk.projects.on('indexing_progress', (data) => {
+  console.log(`Прогресс: ${data.progress}% (${data.indexedFiles}/${data.totalFiles} файлов)`);
+});
+
+sdk.projects.on('indexing_complete', (data) => {
+  console.log(`Индексация завершена! Проиндексировано ${data.indexedFiles} файлов`);
+});
+
+sdk.projects.on('indexing_error', (data) => {
+  console.error(`Ошибка индексации: ${data.message}`);
+});
+
+sdk.projects.on('file_indexed', (data) => {
+  console.log(`Файл проиндексирован: ${data.filePath}`);
+});
+
+sdk.projects.on('error', (error) => {
+  console.error(`Ошибка WebSocket: ${error.message}`);
+});
+```
+
+### Отключение от WebSocket
+
+```javascript
+// Отключение от пространства имен индексации
+await sdk.projects.disconnectWebSocket();
+
+// Или через WebSocketClient
+const wsClient = sdk.getWebSocketClient();
+await wsClient.disconnect(WebSocketNamespace.INDEXING);
+
+// Отключение от всех пространств имен
+await wsClient.disconnectAll();
+```
+
+## События WebSocket
+
+При индексации проектов сервер отправляет следующие типы событий:
+
+| Событие | Описание | Данные |
+|---------|----------|--------|
+| `indexing_start` | Начало процесса индексации | `{ projectId: string }` |
+| `indexing_progress` | Обновление прогресса индексации | `{ projectId: string, totalFiles: number, indexedFiles: number, progress: number, startTime: string, elapsedTime: number, estimatedTimeRemaining?: number }` |
+| `indexing_complete` | Завершение индексации | `{ projectId: string, totalFiles: number, indexedFiles: number, skippedFiles: number, startTime: string, endTime: string, totalTime: number }` |
+| `indexing_error` | Ошибка при индексации | `{ projectId: string, message: string, code?: string, details?: any }` |
+| `file_indexed` | Отдельный файл проиндексирован | `{ projectId: string, filePath: string, fileIndex: object }` |
+| `file_index_error` | Ошибка при индексации файла | `{ projectId: string, filePath: string, message: string }` |
+
+## Обработка ошибок
+
+При работе с индексацией могут возникать различные ошибки. Вот типичные ошибки и способы их обработки:
+
+### Ошибки HTTP API
+
+```javascript
+try {
+  await sdk.projects.indexProject(projectId);
+} catch (error) {
+  if (error.status === 404) {
+    console.error('Проект не найден');
+  } else if (error.status === 409) {
+    console.error('Индексация уже запущена для этого проекта');
+  } else {
+    console.error('Неизвестная ошибка:', error.message);
+  }
+}
+```
+
+### Ошибки WebSocket
+
+```javascript
+// Подключение с обработкой ошибок
+try {
+  await sdk.projects.connectWebSocket();
+} catch (error) {
+  console.error('Ошибка подключения WebSocket:', error);
+}
+
+// Обработчик ошибок WebSocket
+sdk.projects.on('error', (error) => {
+  console.error('Ошибка WebSocket:', error);
+});
+
+// Обработка отключения
+sdk.projects.on('disconnect', () => {
+  console.log('WebSocket соединение прервано');
+  
+  // Автоматическое переподключение
+  setTimeout(async () => {
+    try {
+      await sdk.projects.connectWebSocket();
+      console.log('Переподключено к WebSocket');
+    } catch (error) {
+      console.error('Не удалось переподключиться:', error);
+    }
+  }, 3000);
+});
+```
+
+## Примеры использования
+
+### Базовый пример индексации
+
+```javascript
+// Инициализация SDK
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://localhost:3000',
+  apiKey: 'your-api-key',
+  websocket: {
+    reconnect: true // Автоматическое переподключение
+  }
+});
+
+// Запуск индексации
+async function indexProject(projectId) {
+  try {
+    // Подключаемся к WebSocket пространству имен индексации
+    await sdk.projects.connectWebSocket();
+    
+    // Устанавливаем обработчики событий
+    sdk.projects.on('indexing_progress', (data) => {
+      console.log(`Прогресс: ${data.progress}%`);
+    });
+    
+    sdk.projects.on('indexing_complete', (data) => {
+      console.log('Индексация завершена!');
+    });
+    
+    // Запускаем индексацию
+    const result = await sdk.projects.indexProject(projectId);
+    console.log('Индексация запущена:', result);
+    
+    // Ждем завершения индексации
+    return new Promise((resolve, reject) => {
+      sdk.projects.on('indexing_complete', (data) => {
+        sdk.projects.disconnectWebSocket();
+        resolve(data);
+      });
+      
+      sdk.projects.on('indexing_error', (error) => {
+        sdk.projects.disconnectWebSocket();
+        reject(new Error(error.message));
+      });
+      
+      // Таймаут на случай, если что-то пойдет не так
+      setTimeout(() => {
+        sdk.projects.disconnectWebSocket();
+        reject(new Error('Таймаут индексации'));
+      }, 120000); // 2 минуты
+    });
+  } catch (error) {
+    console.error('Ошибка индексации:', error);
+    throw error;
+  }
+}
+```
+
+### Пример с отображением прогресс-бара
+
+```javascript
+const progressBar = require('progress');
+
+async function indexWithProgressBar(projectId) {
+  // Создаем прогресс-бар
+  let bar = null;
+  
+  // Подключаемся к WebSocket
+  await sdk.projects.connectWebSocket();
+  
+  // Устанавливаем обработчики событий
+  sdk.projects.on('indexing_start', () => {
+    console.log('Индексация началась...');
+  });
+  
+  sdk.projects.on('indexing_progress', (data) => {
+    if (!bar) {
+      bar = new progressBar('Индексация [:bar] :percent :etas', {
+        complete: '=',
+        incomplete: ' ',
+        width: 50,
+        total: 100
+      });
+    }
+    
+    bar.update(data.progress / 100);
+  });
+  
+  sdk.projects.on('indexing_complete', (data) => {
+    if (bar) {
+      bar.update(1.0); // Заполняем прогресс-бар
+    }
+    console.log(`\nИндексация завершена! Обработано ${data.indexedFiles} файлов за ${data.totalTime.toFixed(2)} секунд`);
+  });
+  
+  // Запускаем индексацию
+  await sdk.projects.indexProject(projectId);
+  
+  // Возвращаем Promise, который разрешится при завершении индексации
+  return new Promise((resolve, reject) => {
+    sdk.projects.on('indexing_complete', (data) => {
+      sdk.projects.disconnectWebSocket();
+      resolve(data);
+    });
+    
+    sdk.projects.on('indexing_error', (error) => {
+      sdk.projects.disconnectWebSocket();
+      reject(new Error(error.message));
+    });
+  });
+}
+```
+
+### Инкрементальное обновление файлов при изменении
+
+```javascript
+const fs = require('fs');
+const path = require('path');
+const chokidar = require('chokidar');
+
+// Функция для наблюдения за изменениями в директории и инкрементальной индексации
+async function watchAndIndex(projectId, dirPath) {
+  // Подключение WebSocket для получения уведомлений о индексации
+  await sdk.projects.connectWebSocket();
+  
+  // Устанавливаем обработчики для отдельных файлов
+  sdk.projects.on('file_indexed', (data) => {
+    console.log(`Файл проиндексирован: ${data.filePath}`);
+  });
+  
+  sdk.projects.on('file_index_error', (data) => {
+    console.error(`Ошибка индексации файла ${data.filePath}: ${data.message}`);
+  });
+  
+  // Создаем наблюдателя за файловой системой
+  const watcher = chokidar.watch(dirPath, {
+    ignored: /(^|[\/\\])\../, // Игнорировать скрытые файлы
+    persistent: true,
+    ignoreInitial: true
+  });
+  
+  // При изменении файла, обновляем его индекс
+  watcher.on('change', async (filePath) => {
+    try {
+      // Получаем путь относительно корня проекта
+      const relPath = path.relative(dirPath, filePath);
+      
+      console.log(`Файл изменился: ${relPath}`);
+      
+      // Обновляем индекс файла
+      await sdk.projects.updateFileIndex(projectId, relPath);
+      
+      console.log(`Отправлен запрос на обновление индекса файла: ${relPath}`);
+    } catch (error) {
+      console.error(`Ошибка обновления индекса: ${error.message}`);
+    }
+  });
+  
+  console.log(`Наблюдение за директорией ${dirPath} началось`);
+  
+  // Возвращаем функцию для остановки наблюдения
+  return () => {
+    watcher.close();
+    sdk.projects.disconnectWebSocket();
+    console.log('Наблюдение остановлено');
+  };
+}
+```
+
+Дополнительные примеры использования API индексации можно найти в файле `solver-sdk/examples/indexing-example.js`.