diffray 0.1.3 → 0.3.1

package/dist/defaults/prompts/SUMMARY.md

@@ -0,0 +1,276 @@
+# Prompts Summary
+
+Полная сводка всех промптов в системе diffray.
+
+## 📊 Статистика
+
+- **Всего промптов**: 7
+- **Автоматических**: 1 (`output-format.md`)
+- **Специализированных**: 6
+- **Документация**: 2 файла (README.md, INDEX.md)
+- **Общий размер**: ~35KB
+- **Строк кода**: ~1012
+
+## 🔄 Автоматические промпты
+
+### `output-format.md` ⚙️
+**Статус**: Автоматически добавляется ко всем агентам  
+**Размер**: 2.3KB  
+**Использование**: Через `loadOutputFormat()` в `executors/utils.ts`
+
+```typescript
+// Автоматически добавляется к каждому агенту
+const format = await loadOutputFormat();
+const fullPrompt = buildPrompt(systemPrompt, input, format);
+```
+
+**Содержит**:
+- JSON структуру вывода
+- Описание полей (file, lineStart, lineEnd, severity, category)
+- Критические требования к формату
+- Примеры правильного вывода
+
+---
+
+## ✅ Специализированные промпты
+
+### 1. `validation.md` 
+**Статус**: Используется агентом валидации  
+**Размер**: 6.7KB  
+**Агент**: `validation.md` в `src/defaults/agents/`
+
+**Назначение**: Фильтрация ложных срабатываний и валидация найденных проблем
+
+**Ключевые разделы**:
+- Процесс верификации (обязательное использование Read tool)
+- Критерии сохранения (реальные, проверенные проблемы)
+- Критерии фильтрации (ложные срабатывания, шум, спекуляции)
+- Распознавание намеренных trade-offs
+- Примеры паттернов фильтрации
+
+---
+
+### 2. `i18n.md` 🌍
+**Статус**: Используется агентом i18n  
+**Размер**: 2.8KB  
+**Агент**: `i18n.md` в `src/defaults/agents/`
+
+**Назначение**: Проверка интернационализации кода
+
+**Фокус**:
+- Hardcoded строки
+- Отсутствующие ключи переводов
+- Проблемы с форматами локалей (даты, числа, валюта)
+- Поддержка RTL (справа налево)
+- Проблемы конкатенации строк
+- Проблемы файлов переводов
+
+**Примеры проблем**:
+```typescript
+// ❌ Плохо
+<button>Submit</button>
+
+// ✅ Хорошо
+<button>{t('submit')}</button>
+```
+
+---
+
+### 3. `database.md` 🗄️
+**Статус**: Используется агентом database  
+**Размер**: 3.3KB  
+**Агент**: `database.md` в `src/defaults/agents/`
+
+**Назначение**: Проверка работы с базами данных и ORM
+
+**Фокус**:
+- N+1 проблемы запросов
+- Отсутствующие индексы
+- Проблемы миграций
+- Производительность запросов
+- Риски deadlock
+- Целостность данных
+- ORM-специфичные проблемы
+
+**Примеры проблем**:
+```typescript
+// ❌ Плохо - N+1 запросы
+users.forEach(user => {
+  const posts = db.query('SELECT * FROM posts WHERE user_id = ?', [user.id])
+})
+
+// ✅ Хорошо - Один запрос с JOIN
+const usersWithPosts = db.query('SELECT * FROM users JOIN posts ON users.id = posts.user_id')
+```
+
+---
+
+### 4. `api-design.md` 🔌
+**Статус**: Используется агентом api-design  
+**Размер**: 3.6KB  
+**Агент**: `api-design.md` в `src/defaults/agents/`
+
+**Назначение**: Проверка дизайна REST/GraphQL API
+
+**Фокус**:
+- Неправильное использование HTTP методов
+- Соглашения по именованию
+- Форматы ответов об ошибках
+- Пагинация
+- Версионирование
+- Дизайн запросов/ответов
+- Rate limiting и безопасность
+- GraphQL-специфичные проблемы
+
+**Примеры проблем**:
+```typescript
+// ❌ Плохо - POST для чтения
+POST /api/getUsers
+
+// ✅ Хорошо - GET для чтения
+GET /api/users
+```
+
+---
+
+### 5. `observability.md` 📊
+**Статус**: Используется агентом observability  
+**Размер**: 3.8KB  
+**Агент**: `observability.md` в `src/defaults/agents/`
+
+**Назначение**: Проверка логирования, мониторинга и отслеживания ошибок
+
+**Фокус**:
+- Отсутствующее логирование
+- Неструктурированное логирование
+- Отсутствующий контекст (request_id, trace_id)
+- Отслеживание ошибок
+- Метрики и мониторинг
+- Безопасность и приватность в логах
+- Распределенный трейсинг
+
+**Примеры проблем**:
+```typescript
+// ❌ Плохо - Тихая обработка ошибок
+try {
+  await processPayment()
+} catch (error) {
+  // Ничего не логируется!
+}
+
+// ✅ Хорошо - Логирование с контекстом
+try {
+  await processPayment()
+} catch (error) {
+  logger.error('Payment processing failed', {
+    error,
+    request_id: ctx.requestId,
+    user_id: ctx.userId
+  })
+}
+```
+
+---
+
+### 6. `data-privacy.md` 🔒
+**Статус**: Используется агентом data-privacy  
+**Размер**: 4.4KB  
+**Агент**: `data-privacy.md` в `src/defaults/agents/`
+
+**Назначение**: Проверка обработки персональных данных и соответствия GDPR
+
+**Фокус**:
+- Раскрытие PII
+- Отсутствующие проверки согласия
+- Хранение данных
+- Шифрование и хранение
+- Доступ к данным и портируемость
+- Обмен данными с третьими лицами
+- Минимизация данных
+
+**Примеры проблем**:
+```typescript
+// ❌ Плохо - PII в логах без маскировки
+logger.info('User signed up', { email: user.email })
+
+// ✅ Хорошо - Email замаскирован
+logger.info('User signed up', { 
+  email: maskEmail(user.email),
+  user_id: user.id 
+})
+```
+
+---
+
+## 📚 Документация
+
+### `README.md` (4.2KB)
+Полная документация по использованию промптов:
+- Описание всех промптов
+- Инструкции по использованию
+- Примеры создания новых промптов
+- Best practices
+
+### `INDEX.md` (3.8KB)
+Быстрая справка по всем промптам:
+- Краткое описание каждого промпта
+- Статистика по строкам
+- Паттерны использования
+- Связанная документация
+
+---
+
+## 🔗 Связи промптов и агентов
+
+| Промпт | Агент | Статус |
+|--------|-------|--------|
+| `output-format.md` | Все агенты | Автоматически |
+| `validation.md` | `validation` | Используется |
+| `i18n.md` | `i18n` | Используется |
+| `database.md` | `database` | Используется |
+| `api-design.md` | `api-design` | Используется |
+| `observability.md` | `observability` | Используется |
+| `data-privacy.md` | `data-privacy` | Используется |
+
+---
+
+## 🚀 Использование
+
+### Автоматическое включение
+`output-format.md` автоматически добавляется ко всем агентам через `loadOutputFormat()`.
+
+### Ручное включение
+Агенты могут ссылаться на специализированные промпты в своих markdown файлах:
+
+```markdown
+---
+name: my-agent
+---
+
+You are a database reviewer.
+
+See ../prompts/database.md for detailed guidelines.
+```
+
+---
+
+## 📝 Создание новых промптов
+
+1. Создайте файл в `src/defaults/prompts/`
+2. Добавьте структуру:
+   - Mission statement
+   - Focus areas
+   - Quality standards
+   - Instructions
+   - Examples
+3. Создайте соответствующий агент в `src/defaults/agents/`
+4. Обновите документацию (README.md, INDEX.md)
+
+---
+
+## 📖 Связанные файлы
+
+- **Агенты**: `src/defaults/agents/`
+- **Загрузка промптов**: `src/executors/utils.ts`
+- **Документация агентов**: `docs/AGENTS.md`
+- **Архитектура**: `docs/ARCHITECTURE.md`

package/dist/defaults/prompts/USAGE.md

@@ -0,0 +1,277 @@
+# Использование промптов - Практические примеры
+
+Практическое руководство по использованию промптов в diffray.
+
+## 🔄 Как промпты загружаются и используются
+
+### Автоматическое включение (output-format.md)
+
+Промпт `output-format.md` автоматически добавляется ко всем агентам:
+
+```typescript
+// В executors/utils.ts
+export async function loadOutputFormat(): Promise<string> {
+  return getCached(CACHE_KEYS.OUTPUT_FORMAT, async () => {
+    try {
+      const formatPath = getDefaultPath('prompts', 'output-format.md');
+      return await readFile(formatPath, 'utf-8');
+    } catch {
+      return DEFAULT_OUTPUT_FORMAT; // Fallback
+    }
+  });
+}
+
+// Использование в executors/cli.ts
+const format = await loadOutputFormat();
+const fullPrompt = buildPrompt(systemPrompt, ctx.input, format);
+// Результат: systemPrompt + "\n\n# Input:\n" + input + "\n\n" + format
+```
+
+**Что происходит**:
+1. `loadOutputFormat()` загружает `output-format.md`
+2. `buildPrompt()` объединяет systemPrompt агента + input (диффы) + format
+3. Итоговый промпт отправляется в LLM
+
+---
+
+## 📝 Использование специализированных промптов
+
+### Вариант 1: Прямое включение в агента
+
+Агент может включать содержимое промпта напрямую:
+
+```markdown
+---
+name: i18n
+description: Checks for internationalization issues
+enabled: true
+---
+
+You are an internationalization specialist reviewing code for i18n issues.
+
+**Focus Areas**:
+- Hardcoded strings
+- Missing translation keys
+- Locale format issues
+- RTL support
+
+[Содержимое из prompts/i18n.md можно включить здесь]
+```
+
+### Вариант 2: Ссылка на промпт
+
+Агент может ссылаться на промпт:
+
+```markdown
+---
+name: database
+description: Detects database issues
+enabled: true
+---
+
+You are a database specialist.
+
+See ../prompts/database.md for detailed review guidelines.
+
+Focus on:
+- N+1 queries
+- Missing indexes
+- Migration safety
+```
+
+### Вариант 3: Комбинирование промптов
+
+Агент может комбинировать несколько промптов:
+
+```markdown
+---
+name: full-stack-reviewer
+description: Comprehensive code review
+enabled: true
+---
+
+You are a full-stack code reviewer.
+
+**Database Review**: See ../prompts/database.md
+**API Design**: See ../prompts/api-design.md
+**Observability**: See ../prompts/observability.md
+
+Review code for issues in all these areas.
+```
+
+---
+
+## 🎯 Примеры использования
+
+### Пример 1: Агент с автоматическим форматом
+
+```typescript
+// Агент: bug-hunter.md
+// System prompt: "You are a bug detection specialist..."
+// Input: Git diffs
+// Format: Автоматически добавляется из output-format.md
+
+// Итоговый промпт:
+const finalPrompt = `
+You are a bug detection specialist focused on identifying logic errors.
+
+# Input:
+File: src/utils.ts
++ function processData(data) {
++   return data.map(item => item.value);
++ }
+
+# Output Format
+Return your findings as a JSON array wrapped in <json>...</json> XML tags:
+...
+`;
+```
+
+### Пример 2: Агент валидации
+
+```typescript
+// Агент: validation.md
+// Использует промпт validation.md напрямую
+// Stage: validation (отдельный этап)
+
+const validationPrompt = `
+You are a strict code review validation agent.
+Your task is to validate issues found by other agents...
+
+[Содержимое из prompts/validation.md]
+`;
+```
+
+### Пример 3: Специализированный агент
+
+```typescript
+// Агент: database.md
+// System prompt включает фокус на базы данных
+// Format: Автоматически добавляется
+
+const databasePrompt = `
+You are a database specialist reviewing code for SQL/ORM issues.
+
+**Focus Areas**:
+- N+1 query problems
+- Missing indexes
+- Migration issues
+...
+
+# Input:
+[Git diffs с изменениями в database коде]
+
+# Output Format
+[Автоматически из output-format.md]
+`;
+```
+
+---
+
+## 🔧 Создание нового промпта и агента
+
+### Шаг 1: Создать промпт
+
+```bash
+# Создать файл промпта
+touch src/defaults/prompts/my-domain.md
+```
+
+```markdown
+# My Domain Review Prompt
+
+You are a specialist reviewing code for [domain] issues.
+
+## Your Mission
+Identify [specific problems] that will cause [impact].
+
+## Focus Areas
+- Area 1: Description
+- Area 2: Description
+
+## Quality Standards
+- Only flag issues with actual impact
+- Verify before reporting
+- Be concise and actionable
+
+## Instructions
+- Provide specific examples
+- Suggest concrete fixes
+- Only report real problems
+```
+
+### Шаг 2: Создать агента
+
+```bash
+# Создать файл агента
+touch src/defaults/agents/my-domain.md
+```
+
+```markdown
+---
+name: my-domain
+description: Reviews code for [domain] issues
+enabled: true
+---
+
+You are a [domain] specialist reviewing code.
+
+**Focus Areas**:
+- [Area 1]
+- [Area 2]
+
+[Можно включить содержимое из prompts/my-domain.md или ссылаться на него]
+```
+
+### Шаг 3: Обновить документацию
+
+Обновите `README.md`, `INDEX.md`, и `SUMMARY.md` с информацией о новом промпте.
+
+---
+
+## 📊 Структура промпта
+
+Рекомендуемая структура промпта:
+
+```markdown
+# [Domain] Review Prompt
+
+## Your Mission
+[Четкое описание цели]
+
+## Focus Areas
+### 1. [Area 1]
+- [Подпункты]
+
+### 2. [Area 2]
+- [Подпункты]
+
+## Quality Standards
+- [Критерии качества]
+
+## Instructions
+- [Инструкции по использованию]
+
+## Examples of Issues to Report
+✅ **Report**: [Пример проблемы]
+❌ **Don't Report**: [Пример того, что не нужно флажить]
+```
+
+---
+
+## 🚀 Best Practices
+
+1. **Будьте конкретны**: Четкие инструкции дают лучшие результаты
+2. **Приводите примеры**: Показывайте, что флажить, а что нет
+3. **Фокус на impact**: Только реальные проблемы, не микро-оптимизации
+4. **Обновляйте регулярно**: Улучшайте промпты на основе реального использования
+5. **Документируйте**: Обновляйте README при создании новых промптов
+
+---
+
+## 🔗 Связанные файлы
+
+- **Загрузка промптов**: `src/executors/utils.ts` → `loadOutputFormat()`
+- **Использование**: `src/executors/cli.ts` → `buildPrompt()`
+- **Агенты**: `src/defaults/agents/` - Агенты, использующие промпты
+- **Документация**: `README.md`, `INDEX.md`, `SUMMARY.md`

package/dist/defaults/prompts/api-design.md

@@ -0,0 +1,119 @@
+# API Design Review Prompt
+
+You are an API design specialist reviewing REST/GraphQL API endpoints for design issues, naming inconsistencies, and best practices violations.
+
+## Your Mission
+
+Identify API design flaws, inconsistent naming conventions, missing error formats, pagination issues, and versioning problems that will cause integration difficulties or scalability issues.
+
+## Focus Areas
+
+### 1. **HTTP Method Misuse**
+- Using POST for read operations (should be GET)
+- Using GET for state-changing operations (should be POST/PUT/DELETE)
+- Missing proper HTTP status codes
+- Using wrong status codes (200 for errors, etc.)
+
+### 2. **Naming Conventions**
+- Inconsistent endpoint naming (camelCase vs snake_case vs kebab-case)
+- Non-RESTful resource names (e.g., `/getUsers` instead of `/users`)
+- Verbs in URLs (should use HTTP methods)
+- Plural vs singular inconsistencies
+
+### 3. **Error Response Format**
+- Missing consistent error response structure
+- Error responses without error codes
+- Missing error details or context
+- Inconsistent error format across endpoints
+
+### 4. **Pagination**
+- Endpoints returning unbounded lists (missing pagination)
+- Inconsistent pagination parameters across endpoints
+- Missing total count or has_more indicators
+- Inefficient pagination (offset-based for large datasets)
+
+### 5. **Versioning**
+- Missing API versioning strategy
+- Breaking changes without version bump
+- Inconsistent versioning format (v1 vs v1.0 vs 1.0)
+
+### 6. **Request/Response Design**
+- Missing request validation
+- Returning too much data (over-fetching)
+- Missing fields that clients need (under-fetching)
+- Inconsistent field naming across endpoints
+
+### 7. **Rate Limiting & Security**
+- Missing rate limiting headers
+- No authentication/authorization checks
+- Sensitive data in URLs (should be in body/headers)
+- Missing CORS configuration
+
+### 8. **GraphQL-Specific Issues**
+- N+1 query problems in resolvers
+- Missing query complexity limits
+- Over-fetching due to missing field selection
+- Missing error handling in resolvers
+
+## Quality Standards
+
+- Only flag issues with actual API design impact
+- Distinguish between acceptable patterns and violations
+- Check if framework conventions are being followed
+- Verify the issue will cause real integration problems
+
+## Instructions
+
+- Be concise and actionable
+- Provide specific examples of the problematic pattern
+- Suggest concrete fixes (rename endpoint, add pagination, etc.)
+- Only report issues that will cause real API design problems
+
+## Examples of Issues to Report
+
+✅ **Report**: Wrong HTTP method
+```typescript
+// ❌ Bad - POST for read operation
+POST /api/getUsers
+
+// ✅ Good - GET for read operation
+GET /api/users
+```
+
+✅ **Report**: Missing pagination
+```typescript
+// ❌ Bad - Unbounded list
+GET /api/users
+// Returns all users (could be millions)
+
+// ✅ Good - Paginated
+GET /api/users?page=1&limit=20
+```
+
+✅ **Report**: Inconsistent error format
+```typescript
+// ❌ Bad - Inconsistent formats
+{ error: "Not found" }           // Endpoint 1
+{ message: "User not found" }    // Endpoint 2
+{ code: 404, details: "..." }    // Endpoint 3
+
+// ✅ Good - Consistent format
+{ error: { code: "NOT_FOUND", message: "User not found" } }
+```
+
+✅ **Report**: Non-RESTful naming
+```typescript
+// ❌ Bad - Verbs in URL
+POST /api/createUser
+POST /api/deleteUser
+
+// ✅ Good - RESTful resources
+POST /api/users
+DELETE /api/users/:id
+```
+
+❌ **Don't Report**: Framework-specific conventions that are acceptable
+```typescript
+// OK - Framework convention (e.g., Next.js API routes)
+POST /api/users/create  // If framework expects this pattern
+```