Code Solver SDK v5.1.0

🗑️ Ультра-чистый JavaScript/TypeScript SDK для VS Code Extensions
Без legacy кода, без мертвых методов, только актуальный API

JavaScript/TypeScript SDK для работы с Code Solver API. Предоставляет простой интерфейс для индексации кода, семантического поиска функций, работы с AI чатом и новую Delta-Chunking архитектуру для Cursor-подобной синхронизации проектов.

🎯 Основные возможности

🔄 Delta-Chunking - Cursor-like инкрементальная синхронизация проектов
💬 Chat API - взаимодействие с AI моделями (Claude, GPT)
🔍 Code Search - семантический поиск по коду и функциям
📊 Project Indexing - индексация и анализ проектов с богатой информацией
📝 Context API - получение контекста для AI
🛠️ Code Modification - модификация кода через AI
🔇 Настраиваемое логирование - полный контроль над выводом в консоль
✨ Улучшенная типизация - полные TypeScript типы с примерами и документацией

🚀 Что нового в v5.1.0

🔄 Delta-Chunking API - добавлена полная документация для новой архитектуры синхронизации

✨ Delta-Chunking интеграция - встроено в основной CodeSolverSDK класс
📝 Полная документация - все методы, типы и примеры использования
🔐 Шифрование и chunking - конфигурация encryption и chunking опций
🎯 Готово к продакшену - интеграция с backend полностью реализована

📦 Установка

npm install solver-sdk

⚙️ Конфигурация

const sdk = await CodeSolverSDK.create({
  baseURL: 'http://localhost:3000',     // Обязательный  
  apiKey: 'your-api-key',               // Опционально
  timeout: 30000,                       // Таймаут запросов (мс)
  debug: 'error'                        // Уровень логирования
});

📊 Уровни логирования

'silent' - полное отключение
'error' - только ошибки (рекомендуется)
'warn' - предупреждения и ошибки
'info' - базовая информация
'debug' - подробная отладка

🚀 Быстрый старт

import { CodeSolverSDK } from 'solver-sdk';

// Создание SDK
const sdk = await CodeSolverSDK.create({
  baseURL: 'http://localhost:3000',
  debug: 'error' // Рекомендуемый уровень для production
});

// 1. Создание проекта (с автоматической дедупликацией)
const project = await sdk.projects.createProject(
  'My Project',
  '/path/to/project'
);

// 2. Запуск индексации
await sdk.projects.startIndexing(project.id);

// 3. Проверка статуса
const status = await sdk.projects.getIndexingStatus(project.id);
console.log(`Статус: ${status.status}, прогресс: ${status.progress}%`);

// 4. Поиск в коде
const results = await sdk.search.searchCode(project.id, {
  query: 'function calculateSum',
  limit: 10
});

// 5. Чат с AI
const response = await sdk.chat.chat([
  { role: 'user', content: 'Объясни найденный код' }
], { projectId: project.id });

console.log(response.content);

📋 API Методы

📁 Projects API

// Создание проекта
await sdk.projects.createProject('Project Name', '/project/path');
await sdk.projects.createProject('Project Name', '/project/path', { description: 'Optional' });

// Получение проектов
await sdk.projects.getAllProjects();       // Все проекты
await sdk.projects.getReadyProjects();     // Только готовые к работе
await sdk.projects.getProject(projectId);  // Конкретный проект с полной информацией

⚙️ Indexing API

// Управление индексацией
await sdk.projects.startIndexing(projectId);
await sdk.projects.cancelIndexing(projectId);

// Статус индексации
const status = await sdk.projects.getIndexingStatus(projectId);
console.log(`${status.status}: ${status.progress}%`);

🔍 Search API

// Поиск в коде
const results = await sdk.search.searchCode(projectId, {
  query: 'function name',
  limit: 20
});

// Поиск функций
const functions = await sdk.search.searchFunctions(projectId, {
  query: 'calculateSum', 
  limit: 10
});

// Статистика
const stats = await sdk.search.getFunctionStats(projectId);

💬 Chat API

// Обычный чат
const response = await sdk.chat.chat([
  { role: 'user', content: 'Explain this code' }
], { projectId });

// Потоковый чат  
for await (const chunk of sdk.chat.streamChat(messages, { projectId })) {
  console.log(chunk.text);
}

// С thinking (мышление Claude)
const response = await sdk.chat.chat(messages, { 
  projectId,
  thinking: { type: 'enabled', budget_tokens: 5000 }
});

🔄 Delta-Chunking API

🚀 Новый Cursor-подобный подход к синхронизации проектов
Инкрементальные обновления, шифрование, real-time статус

Создание SDK с Delta-Chunking

import { CodeSolverSDK } from 'solver-sdk';

// Создание SDK с включенным delta-chunking
const sdk = await CodeSolverSDK.create({
  baseURL: 'http://localhost:3000',
  apiKey: 'your-api-key',
  deltaChunking: {                          // ✨ Опциональная секция
    enabled: true,                          // Включить delta-chunking
    encryption: {
      enabled: true,
      key: 'your-32-char-encryption-key-here!'  // 32 символа
    },
    chunking: {
      maxTokens: 400,                       // Максимальный размер чанка
      minTokens: 100,                       // Минимальный размер чанка  
      useTreeSitter: false,                 // Пока простая разбивка
      preserveContext: true                 // Сохранять контекст между чанками
    },
    fileWatching: {
      enabled: false,                       // Автоматическое наблюдение (в разработке)
      pollInterval: 1000,                   // Интервал проверки изменений
      ignorePatterns: ['node_modules/**']   // Игнорируемые файлы
    }
  },
  debug: 'error'
});

// Проверяем что delta-chunking включен
console.log('Delta-chunking доступен:', sdk.isDeltaChunkingEnabled);

Синхронизация проекта

// Основной метод синхронизации (только если deltaChunking.enabled = true)
const result = await sdk.syncProject('project-id', '/path/to/project', {
  forceFull: false,           // Инкрементальная синхронизация 
  batchSize: 50,             // Чанков за раз
  ignorePatterns: [          // Игнорировать файлы/папки
    'node_modules/**', 
    '*.log',
    '.git/**'
  ],
  includeExtensions: ['.ts', '.js', '.py'],  // Только эти расширения
  maxFileSizeKB: 1024,       // Максимальный размер файла 1MB
  onProgress: (current, total) => {          // Callback прогресса
    console.log(`Прогресс: ${current}/${total} (${Math.round(current/total*100)}%)`);
  }
});

console.log(`✅ Синхронизация завершена: ${result.processedChunks} чанков`);

Синхронизация файлов (для браузера)

// Для web/браузерных приложений без доступа к файловой системе
const files = [
  {
    path: 'src/index.ts',
    content: 'console.log("Hello World");',
    size: 28
  },
  {
    path: 'src/utils.ts', 
    content: 'export const sum = (a, b) => a + b;',
    size: 37
  }
];

const result = await sdk.syncFiles('project-id', files, {
  batchSize: 20,
  onProgress: (current, total) => {
    console.log(`📤 Загружено: ${current}/${total}`);
  }
});

Автоматическое наблюдение за изменениями

// Запуск file watcher (в разработке)
const watcher = await sdk.startAutoSync('project-id', '/path/to/watch');

// Проверка активности
console.log(`👀 Auto-sync активен: ${watcher.isActive}`);

// Остановка наблюдения
await watcher.stop();
console.log('🔴 File watcher остановлен');

Статус и управление

// Проверка статуса синхронизации
const status = await sdk.getSyncStatus('project-id');
console.log(`📊 Статус: ${status.status}, прогресс: ${status.progress || 0}%`);

// Отмена активной синхронизации
const cancelled = await sdk.cancelSync('project-id');
if (cancelled) {
  console.log('❌ Синхронизация отменена');
}

Полный пример workflow

import { CodeSolverSDK } from 'solver-sdk';

async function syncProject() {
  // 1. Создание SDK
  const sdk = await CodeSolverSDK.create({
    baseURL: 'http://localhost:3000',
    deltaChunking: {
      enabled: true,
      encryption: { enabled: true, key: 'my-secret-key-32-characters-long!' }
    },
    debug: 'info'
  });

  try {
    // 2. Синхронизация с прогрессом
    const result = await sdk.syncProject('my-project-id', './my-project', {
      onProgress: (current, total) => {
        const percent = Math.round((current / total) * 100);
        console.log(`🔄 Синхронизация: ${percent}% (${current}/${total} чанков)`);
      },
      ignorePatterns: ['node_modules/**', 'dist/**', '*.log']
    });

    // 3. Результат
    console.log('🎉 Синхронизация завершена:', {
      success: result.success,
      processedChunks: result.processedChunks,
      duration: result.duration + 'ms',
      newFiles: result.details?.newFiles,
      changedFiles: result.details?.changedFiles
    });

    // 4. Проверка финального статуса
    const status = await sdk.getSyncStatus('my-project-id');
    console.log(`✅ Финальный статус: ${status.status}`);

  } catch (error) {
    console.error('❌ Ошибка синхронизации:', error.message);
    
    // Отменяем если что-то пошло не так
    await sdk.cancelSync('my-project-id');
  }
}

// Запуск
syncProject();

💡 Типы данных

Project

interface Project {
  id: string;
  name: string; 
  path: string;
  ready: boolean;              // Готов к работе
  fileCount: number;           // Количество файлов
  indexStatus: 'pending' | 'indexing' | 'indexed' | 'failed' | 'cancelled';
  indexingProgress?: number;   // 0-100%
  languageStats?: {[lang: string]: number};  // Статистика языков
  indexingErrors?: any[];      // Ошибки индексации
  // ... и еще 10+ полей
}

Delta-Chunking Types

// Расширенная конфигурация CodeSolverSDK с delta-chunking
interface CodeSolverSDKOptions {
  baseURL: string;
  apiKey?: string;
  deltaChunking?: {                        // ✨ Опциональная секция
    enabled: boolean;                      // Включение delta-chunking функциональности
    
    encryption?: {
      enabled: boolean;                    // Включить шифрование чанков
      key: string;                         // 32-символьный ключ для AES-256
    };
    
    chunking?: {
      maxTokens?: number;                  // Максимальный размер чанка (по умолчанию: 400)
      minTokens?: number;                  // Минимальный размер чанка (по умолчанию: 100)
      useTreeSitter?: boolean;             // Использовать tree-sitter парсер (в разработке)
      preserveContext?: boolean;           // Сохранять контекст между чанками
    };
    
    fileWatching?: {
      enabled: boolean;                    // Включить автоматическое наблюдение за изменениями
      pollInterval?: number;               // Интервал проверки изменений в мс (по умолчанию: 1000)
      ignorePatterns?: string[];           // Паттерны для игнорирования файлов
    };
  };
  timeout?: number;                        // Таймаут запросов (мс)
  debug?: 'silent' | 'error' | 'warn' | 'info' | 'debug';
}

// Опции синхронизации
interface SyncOptions {
  forceFull?: boolean;         // Принудительная полная синхронизация
  batchSize?: number;          // Размер батча для загрузки чанков (по умолчанию: 50)
  ignorePatterns?: string[];   // Паттерны для игнорирования файлов
  includeExtensions?: string[]; // Включать только определенные расширения
  maxFileSizeKB?: number;      // Максимальный размер файла для обработки (KB)
  onProgress?: (current: number, total: number) => void; // Callback прогресса
  timeoutMs?: number;          // Таймаут для операций
}

// Результат синхронизации
interface SyncResult {
  success: boolean;
  projectId: string;
  sessionId?: string;
  processedChunks: number;
  totalChunks: number;
  duration: number;            // Время выполнения в мс
  error?: string;
  details?: {
    newFiles: number;
    changedFiles: number;
    deletedFiles: number;
    failedChunks: number;
  };
}

// Статус синхронизации
interface SyncStatus {
  status: 'inactive' | 'initializing' | 'active' | 'finalizing' | 'completed' | 'failed';
  progress?: number;           // 0-100%
  chunksReceived?: number;
  chunksProcessed?: number;
  sessionId?: string;
  errors?: string[];
  startTime?: Date;
  estimatedCompletion?: Date;
}

// File watcher для автоматической синхронизации
interface FileWatcher {
  projectId: string;
  watchPath: string;
  isActive: boolean;
  start(): Promise<void>;
  stop(): Promise<void>;
}

// Контент файла
interface FileContent {
  path: string;                // Относительный путь файла
  content: string;             // Содержимое файла
  size: number;                // Размер в байтах
}

📚 Пример использования

import { CodeSolverSDK } from 'solver-sdk';

const sdk = await CodeSolverSDK.create({
  baseURL: 'http://localhost:3000'
});

// Работа с проектом
const project = await sdk.projects.createProject('My App', '/path/to/app');
await sdk.projects.startIndexing(project.id);

// Ожидание индексации
let status;
do {
  status = await sdk.projects.getIndexingStatus(project.id);
  console.log(`${status.status}: ${status.progress}%`);
  await new Promise(r => setTimeout(r, 2000));
} while (status.status === 'indexing');

// Поиск и чат
const results = await sdk.search.searchCode(project.id, { 
  query: 'function main', 
  limit: 5 
});

const response = await sdk.chat.chat([
  { role: 'user', content: 'Explain this code' }
], { projectId: project.id });

🔧 Устранение неполадок

// Проверка подключения
const response = await fetch('http://localhost:3000/health');
console.log('Backend доступен:', response.ok);

// Увеличение таймаута для больших проектов  
const sdk = await CodeSolverSDK.create({
  baseURL: 'http://localhost:3000',
  timeout: 120000  // 2 минуты
});

// Отладка с подробными логами
const sdk = await CodeSolverSDK.create({
  baseURL: 'http://localhost:3000', 
  debug: 'debug'
});

📄 Лицензия

MIT License

Документация актуальна для v5.0.0
История изменений: CHANGELOG.md