Solver SDK

SDK для интеграции с Code Solver Backend API. Поддерживает работу как в браузере, так и в Node.js.

Возможности

• Совместимость с ESM и CommonJS
• Поддержка браузера и Node.js
• Типизация TypeScript
• WebSocket для реалтайм функций
• Поддержка Server-Sent Events (SSE)
• Обработка ошибок и повторные попытки
• Полная документация API

Установка

npm install solver-sdk

Использование

В среде CommonJS (Node.js)

const { CodeSolverSDK } = require('solver-sdk');

// Создание экземпляра SDK
const sdk = new CodeSolverSDK({
  baseURL: 'https://localhost:3000',
  apiKey: 'your-api-key'
});

// Использование SDK
async function example() {
  // Проверка соединения с сервером
  const isHealthy = await sdk.checkHealth();
  console.log('Сервер доступен:', isHealthy);
  
  // Получение списка моделей
  const models = await sdk.reasoning.getModels();
  console.log('Доступные модели:', models);
}

example().catch(console.error);

В среде ESM (Node.js)

// Вариант 1: Динамический импорт через createRequire
import { createRequire } from 'module';
const require = createRequire(import.meta.url);
const { CodeSolverSDK } = require('solver-sdk');

// Вариант 2: Прямой импорт (если в package.json указан "type": "module")
// import * as sdk from 'solver-sdk';
// const { CodeSolverSDK } = sdk;

// Создание экземпляра SDK
const sdk = new CodeSolverSDK({
  baseURL: 'https://localhost:3000',
  apiKey: 'your-api-key'
});

// Пример использования
async function example() {
  const isHealthy = await sdk.checkHealth();
  console.log('Сервер доступен:', isHealthy);
}

example().catch(console.error);

В браузере

<script src="node_modules/solver-sdk/dist/umd/code-solver-sdk.min.js"></script>
<script>
  // SDK доступен глобально как CodeSolverSDK
  const sdk = new CodeSolverSDK.default({
    baseURL: 'https://localhost:3000',
    apiKey: 'your-api-key'
  });
  
  // Пример использования
  sdk.checkHealth()
    .then(isHealthy => console.log('Сервер доступен:', isHealthy))
    .catch(console.error);
</script>

Примеры

Работа с проектами

// Получение списка проектов
const projects = await sdk.projects.getAllProjects();
console.log('Проекты:', projects);

// Создание нового проекта
const newProject = await sdk.projects.createProject('Мой проект', '/path/to/project');
console.log('Новый проект:', newProject);

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

Поиск кода

// Поиск кода
const searchResults = await sdk.search.searchCode(projectId, {
  query: 'function example',
  limit: 10
});
console.log('Результаты поиска:', searchResults);

// Семантический поиск кода
const semanticResults = await sdk.search.semanticSearch(projectId, {
  query: 'функция для обработки HTTP запросов',
  limit: 10
});
console.log('Семантические результаты:', semanticResults);

Работа с рассуждениями через WebSocket

// Создание рассуждения
const reasoning = await sdk.reasoning.createReasoning({
  projectId: projectId,
  query: 'Объясни, как работает этот проект'
});

// Запуск процесса рассуждения
await sdk.reasoning.startReasoning(reasoning.id);

// Подключение через WebSocket
const wsClient = sdk.getWebSocketClient();
await wsClient.connectToReasoning(reasoning.id);

// Обработка событий
wsClient.on('thinking', (data) => {
  console.log('Размышление:', data.content);
});

wsClient.on('complete', (data) => {
  console.log('Завершено:', data.content);
  wsClient.disconnectAll();
});

API для работы с зависимостями

SDK предоставляет API для работы с зависимостями файлов в проекте, что позволяет анализировать структуру проекта, импорты/экспорты и выявлять циклические зависимости.

Получение зависимостей файла

// Получение зависимостей конкретного файла
const fileDependencies = await sdk.dependencies.getFileDependencies(projectId, {
  filePath: 'src/app.js'
});

console.log('Импорты:', fileDependencies.imports);
console.log('Импортируется в:', fileDependencies.importedBy);
console.log('Экспорты:', fileDependencies.exports);
console.log('Экспортируемые из импортов:', fileDependencies.exportedBy);

Получение графа зависимостей

// Получение полного графа зависимостей проекта
const dependencyGraph = await sdk.dependencies.getDependencyGraph(projectId);

console.log('Узлы графа:', dependencyGraph.nodes);
console.log('Связи в графе:', dependencyGraph.edges);

Анализ зависимостей

// Анализ графа зависимостей и поиск циклов
const analysis = await sdk.dependencies.analyzeDependencyGraph(projectId);

console.log('Циклические зависимости:', analysis.cycles);
console.log('Статистика графа:', analysis.statistics);

Статистика зависимостей

// Получение статистики зависимостей в проекте
const stats = await sdk.dependencies.getDependencyStatistics(projectId);

console.log('Общее количество зависимостей:', stats.totalDependencies);
console.log('Уникальные файлы:', stats.uniqueFiles);
console.log('Импорты:', stats.importCount);
console.log('Экспорты:', stats.exportCount);
console.log('Циклические зависимости:', stats.cyclicDependenciesCount);

Получение связанных компонентов

// Получение связанных компонентов для файла
const relatedComponents = await sdk.dependencies.getRelatedComponents(projectId, {
  filePath: 'src/app.js',
  maxDepth: 3,
  includeIncoming: true,
  includeOutgoing: true,
  maxNodes: 20
});

console.log('Исходный файл:', relatedComponents.source);
console.log('Связанные компоненты:', relatedComponents.nodes);

WebSocket события для зависимостей

Для получения уведомлений об изменениях в зависимостях в реальном времени можно использовать WebSocket:

// Подключение к WebSocket для зависимостей
const wsClient = sdk.getWebSocketClient();
await wsClient.connectToDependencies(projectId);

// Обработка события обновления зависимостей
wsClient.on('dependency_update', (data) => {
  console.log('Обновление зависимостей:', data);
  console.log('Затронутые файлы:', data.affectedFiles);
});

Тестирование и совместимость

SDK тщательно тестируется в различных средах:

# Запуск всех тестов
npm test

# Тесты браузерной совместимости
npm run test:browser

# Тесты Node.js совместимости
npm run test:node

# Тесты VS Code Web совместимости
npm run test:vscode

# Проверка покрытия кода тестами
npm run test:coverage

Поддерживаемые среды

SDK протестирован и работает в следующих средах:

• Браузеры: Chrome 80+, Firefox 72+, Safari 14+, Edge 80+
• Node.js: Версии 14.x и выше (как CommonJS, так и ESM)
• VS Code: Desktop и Web версии

Решение проблем совместимости

Если у вас возникли проблемы с совместимостью, обратитесь к разделу "Устранение неполадок" в файле INTEGRATION.md.

Сборка из исходного кода

Для сборки SDK из исходного кода:

# Установка зависимостей
npm install

# Сборка SDK
npm run build

# Очистка директории сборки
npm run clean

Опции SDK

SDK поддерживает следующие опции при инициализации:

Документация

Подробная документация по использованию SDK доступна в директории docs:

• Начало работы - инструкции по установке и базовому использованию SDK
• Работа с проектами - управление проектами через SDK
• Индексация проектов - работа с индексацией и отслеживание через WebSocket
• Документация API - полная документация по всем методам SDK

Тестирование и локальная разработка

Предварительные требования

Для локальной разработки и тестирования требуется:

• Node.js 16+
• npm 8+
• Запущенный локальный сервер Code Solver Backend (по умолчанию на https://localhost:3000)

Тестирование SDK

SDK включает несколько типов тестов:

Модульные тесты

Эти тесты проверяют внутреннюю логику SDK без взаимодействия с реальным бэкендом:

# Запуск всех тестов
npm test

# Запуск тестов для индексации
npm run test:indexing

Интеграционные тесты

Эти тесты проверяют взаимодействие SDK с реальным бэкендом:

# Запуск интеграционных тестов индексации
npm run test:integration

Важно: Для запуска интеграционных тестов необходимо, чтобы локальный сервер Code Solver Backend был запущен на https://localhost:3000.

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

В директории examples находятся примеры использования SDK:

Проверка подключения к API

Пример проверяет доступность API и WebSocket соединения:

npm run example:check-api

Индексация проектов

Пример демонстрирует процесс индексации проекта с отслеживанием через WebSocket:

npm run example:indexing

Режим разработки

Для запуска SDK в режиме разработки с локальным сервером:

1. Запустите локальный сервер Code Solver Backend
2. Используйте следующие настройки в вашем коде:

const sdk = new CodeSolverSDK({
  baseURL: 'https://localhost:3000',
  apiKey: 'test-api-key',
  httpsAgent: new https.Agent({
    rejectUnauthorized: false // Для самоподписанных сертификатов
  }),
  websocket: {
    reconnect: true,
    rejectUnauthorized: false
  }
});

Игнорирование самоподписанных сертификатов

При разработке с локальным сервером используйте:

# В Node.js скриптах
NODE_TLS_REJECT_UNAUTHORIZED=0 node your-script.js

Лицензия

MIT

API Reference

Основные компоненты

• CodeSolverSDK - Основной класс SDK
• ReasoningApi - API для работы с рассуждениями
• ProjectsApi - API для работы с проектами
• SearchApi - API для поиска кода
• AgentsApi - API для работы с агентами
• ContextApi - API для работы с контекстом кода
• CodeModificationApi - API для модификации кода

Настройка соединения с сервером

const sdk = new CodeSolverSDK({
  baseURL: 'https://localhost:3000', // URL сервера (обязательный параметр)
  apiKey: 'your-api-key',            // API ключ (если требуется)
  timeout: 30000,                   // Таймаут запросов в миллисекундах
  headers: {                        // Дополнительные HTTP заголовки
    'Custom-Header': 'value'
  }
});

Версия 1.0.5

• Улучшена совместимость с CommonJS и ESM модулями
• Добавлена поддержка WebSocket соединений
• Добавлена встроенная зависимость ws для Node.js