solver-sdk 2.7.5 → 3.1.0

package/docs/indexing/INDEXING.md

@@ -1,436 +1,759 @@
-# Индексация проектов v2.5.0
+# 📊 Руководство по индексации проектов
 
-Руководство по индексации проектов в AI Solver SDK v2.5.0.
-
-## Инициализация SDK
+## 🚀 Быстрый старт
 
 ```javascript
-import { CodeSolverSDK } from '@ai-solver/sdk';
+import { CodeSolverSDK } from 'solver-sdk';
 
-const sdk = CodeSolverSDK.create({
-  baseURL: 'http://localhost:3000',
-  apiKey: 'dev_sk_test_12345678',
-  autoConnect: false
+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));
+}
 ```
 
-## Основной workflow индексации
+## 📋 Основные методы индексации
 
-### 1. Создание проекта
+### 1. Поиск/создание проекта
 
-```javascript
-const project = await sdk.projects.create({
-  name: 'My Code Project',
-  path: '/path/to/project',
-  description: 'Project for AI analysis'
-});
+```typescript
+// Найти существующий или создать новый проект
+const project = await sdk.projects.findOrCreateProject(
+  projectPath: string,
+  projectName?: string
+): Promise<Project>
 
-console.log('Project created:', project.id);
+// Примеры:
+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. Запуск индексации
 
-```javascript
-// Запуск индексации проекта
+```typescript
+// Запустить индексацию проекта
+await sdk.projects.startIndexing(
+  projectId: string,
+  options?: IndexingOptions
+): Promise<IndexingResponse>
+
+// Примеры:
 await sdk.projects.startIndexing(project.id);
 
-console.log('Indexing started for project:', project.id);
+await sdk.projects.startIndexing(project.id, {
+  forceFull: true,           // Полная переиндексация
+  excludePatterns: ['node_modules/**', '*.log']
+});
 ```
 
-### 3. Проверка статуса
+**Опции индексации:**
+```typescript
+interface IndexingOptions {
+  forceFull?: boolean;      // Полная переиндексация (по умолчанию: false)
+  excludePatterns?: string[]; // Паттерны исключения
+  includePatterns?: string[]; // Паттерны включения
+  maxFileSize?: number;     // Максимальный размер файла (байты)
+}
+```
 
-```javascript
-// Получение статуса индексации
-const status = await sdk.projects.getIndexingStatus(project.id);
+### 3. Мониторинг статуса
 
-console.log('Indexing status:', status.indexStatus);
-console.log('Progress:', status.indexingProgress);
-console.log('Files indexed:', status.filesIndexed);
+```typescript
+// Получить текущий статус проекта
+const status = await sdk.projects.getProjectStatus(
+  projectId: string
+): Promise<ProjectStatus>
 ```
 
-## WebSocket мониторинг индексации
+**Статус индексации:**
+```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. Управление индексацией
 
-```javascript
-// Подключение к projects WebSocket
-await sdk.projects.connectWebSocket();
-
-// Отслеживание прогресса
-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`);
-});
+```typescript
+// Отменить индексацию
+await sdk.projects.cancelIndexing(projectId: string): Promise<boolean>
 
-// Завершение индексации
-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();
-});
+// Очистить ошибку индексации
+await sdk.projects.clearIndexingError(projectId: string): Promise<boolean>
 
-// Ошибки индексации
-sdk.projects.onIndexingError((error) => {
-  console.error('❌ Indexing error:', error.message);
-  console.error('Project:', error.projectId);
-  console.error('File:', error.fileName);
-  
-  sdk.projects.disconnectWebSocket();
-});
+// Удалить проект
+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 indexProjectWithMonitoring(projectPath, projectName) {
-  const sdk = CodeSolverSDK.create({
-    baseURL: 'http://localhost:3000',
-    apiKey: process.env.AI_SOLVER_API_KEY,
-    autoConnect: false
+async function simpleIndexing(projectPath, projectName) {
+  const sdk = await CodeSolverSDK.create({
+    baseURL: 'http://localhost:3000'
   });
   
   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();
-    });
+    // 1. Создать/найти проект
+    console.log('📁 Создание проекта...');
+    const project = await sdk.projects.findOrCreateProject(projectPath, projectName);
+    console.log(`✅ Проект создан: ${project.id}`);
     
-    // 4. Запуск индексации
-    console.log('🚀 Starting indexing...');
+    // 2. Запустить индексацию
+    console.log('🚀 Запуск индексации...');
     await sdk.projects.startIndexing(project.id);
     
-    // 5. Ожидание завершения
-    while (!indexingComplete) {
-      await new Promise(resolve => setTimeout(resolve, 1000));
+    // 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));
     }
     
-    // 6. Проверка финального статуса
-    const finalStatus = await sdk.projects.getIndexingStatus(project.id);
-    console.log('📋 Final status:', finalStatus);
-    
-    return {
-      success: true,
-      project: project,
-      status: finalStatus
-    };
+    return project;
     
   } 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
-    };
+    console.error('❌ Ошибка:', error.message);
+    throw error;
   }
 }
 
 // Использование
-const result = await indexProjectWithMonitoring(
-  '/path/to/my/project',
-  'My AI Project'
-);
-
-if (result.success) {
-  console.log('🎯 Project ready for AI analysis!');
-} else {
-  console.error('💔 Indexing failed:', result.error);
-}
+const project = await simpleIndexing('/path/to/my-project', 'My Project');
 ```
 
-## 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
+### Продвинутый workflow с обработкой ошибок
 
 ```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"
+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']
+});
 ```
 
-### Indexing Status
+## 🎯 Интеграция с VS Code Extension
+
+### Базовая интеграция
 
 ```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"
-}
-```
+import * as vscode from 'vscode';
+import { CodeSolverSDK } from 'solver-sdk';
 
-### Progress Event
+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();
+  }
+}
 
-```javascript
-{
-  projectId: "proj_abc123",
-  percentage: 75,
-  processedFiles: 112,
-  totalFiles: 150,
-  currentFile: "src/components/App.tsx",
-  status: "indexing",
-  filesPerSecond: 8.5,
-  estimatedTimeRemaining: 4500
+// Регистрация команд в 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);
 }
 ```
 
-### 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
+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
-// Проект не найден
-{
-  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'
+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;
+  }
 }
 
-// Ошибка доступа к файлам
-{
-  status: 500,
-  code: 'FILESYSTEM_ERROR',
-  message: 'Cannot access project files',
-  details: {
-    path: '/path/to/project',
-    error: 'Permission denied'
-  }
+// Использование
+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 ? '✅' : '❌'}
+  `);
 }
 ```
 
-### Стратегия 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;
+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;
       }
-      
-      // Последняя попытка
-      if (attempt === maxRetries) {
-        throw error;
+    }
+    
+  } catch (error) {
+    console.error('💥 Критическая ошибка:', error.message);
+    
+    // Попытка очистки
+    try {
+      if (project?.id) {
+        await sdk.projects.cancelIndexing(project.id);
       }
-      
-      // Задержка между попытками
-      const delay = Math.pow(2, attempt) * 1000;
-      await new Promise(resolve => setTimeout(resolve, delay));
+    } catch (cleanupError) {
+      console.error('Ошибка очистки:', cleanupError.message);
     }
+    
+    throw error;
   }
 }
 ```
 
-## Диагностика проблем
+## 📝 Лучшие практики
 
-### Проверка доступности API
+### 1. Оптимизация производительности
 
 ```javascript
-// Проверка endpoints для индексации
-const diagnostics = await sdk.diagnoseAPI();
-
-const indexingEndpoints = [
-  '/api/v1/projects',
-  '/api/v1/projects/:id/index'
+// ✅ Правильно - исключить ненужные файлы
+const excludePatterns = [
+  'node_modules/**',
+  '.git/**',
+  'dist/**',
+  'build/**',
+  '*.log',
+  '*.tmp',
+  '.cache/**',
+  'coverage/**'
 ];
 
-indexingEndpoints.forEach(endpoint => {
-  const status = diagnostics[endpoint];
-  if (status?.success) {
-    console.log(`✅ ${endpoint} - OK`);
-  } else {
-    console.error(`❌ ${endpoint} - ${status?.error || 'Failed'}`);
-  }
-});
+await sdk.projects.startIndexing(project.id, { excludePatterns });
 ```
 
-### WebSocket диагностика
+### 2. Управление ресурсами
 
 ```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);
+// ✅ Правильно - одно подключение на приложение
+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);
+    }
+  }
 }
 ```
 
-## Рекомендации по производительности
-
-### 1. Используйте WebSocket мониторинг
+### 3. Пользовательский интерфейс
 
 ```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));
+// ✅ Правильно - информативная обратная связь
+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';
+  }
 }
 ```
 
-### 2. Правильно управляйте WebSocket
-
-```javascript
-// ✅ Отключайтесь после завершения
-sdk.projects.onIndexingComplete(() => {
-  sdk.projects.disconnectWebSocket();
-});
-
-// ✅ Отключайтесь при ошибках
-sdk.projects.onIndexingError(() => {
-  sdk.projects.disconnectWebSocket();
-});
-```
-
-### 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);
-});
-```
+Индексация - ключевая функция для работы с поиском и AI анализом кода. Основные шаги:
 
----
+1. **Создание проекта** - `findOrCreateProject()`
+2. **Запуск индексации** - `startIndexing()`  
+3. **Мониторинг прогресса** - `getProjectStatus()`
+4. **Использование результатов** - поиск функций и кода
 
-**Документация индексации для SDK v2.5.0**  
-**Совместимость:** AI Solver Backend v1.0.0  
-**Обновлено:** 28 июня 2025 
+**Помните:**
+- Всегда обрабатывайте ошибки
+- Показывайте прогресс пользователю
+- Исключайте ненужные файлы
+- Тестируйте результаты индексации