qa360 2.1.2 → 2.1.4

package/docs/hooks.md

@@ -0,0 +1,304 @@
+# QA360 Hooks - Déclaratifs et Robustes
+
+## Vue d'ensemble
+
+Les hooks QA360 Phase 3 permettent d'orchestrer des actions avant et après l'exécution des gates de qualité. Ils supportent les commandes shell, Docker Compose, et la synchronisation de services.
+
+## Syntaxe Pack.yml
+
+```yaml
+hooks:
+  beforeAll:
+    - run: "npm install"
+      timeout: 60000
+    - compose: up
+      timeout: 120000
+    - wait_on: "http://localhost:8080/healthz"
+      timeout: 30000
+      method: http
+  
+  beforeEach:
+    - run: "echo 'Starting gate'"
+  
+  afterEach:
+    - run: "echo 'Gate completed'"
+  
+  afterAll:
+    - run: "docker system prune -f"
+    - compose: down
+      timeout: 30000
+
+execution:
+  hook_timeout_ms: 180000
+  on_failure: stop  # stop | continue
+  compose_file: "services.yml"
+```
+
+## Types d'Actions
+
+### 1. Commandes Shell (`run`)
+
+```yaml
+- run: "npm test"
+  timeout: 30000
+```
+
+**Caractéristiques :**
+- Exécution dans le répertoire de travail du pack
+- Variables d'environnement héritées
+- Redirection automatique des secrets
+- Support timeout individuel
+
+### 2. Docker Compose (`compose`)
+
+```yaml
+- compose: up
+  timeout: 120000
+- compose: down
+  timeout: 60000
+```
+
+**Fonctionnalités :**
+- Opérations idempotentes (up multiple = safe)
+- Détection automatique du fichier compose
+- Health checks intégrés
+- Nettoyage automatique des volumes
+
+### 3. Attente de Services (`wait_on`)
+
+```yaml
+- wait_on: "http://localhost:3000/healthz"
+  timeout: 30000
+  method: http  # http | tcp
+
+- wait_on: "localhost:5432"
+  timeout: 15000
+  method: tcp
+```
+
+**Méthodes supportées :**
+- **HTTP** : Attente d'un endpoint (status 200)
+- **TCP** : Attente d'ouverture de port
+
+## Lifecycle Hooks
+
+### `beforeAll`
+Exécuté une fois avant tous les gates.
+**Usage typique :** Setup infrastructure, démarrage services.
+
+### `beforeEach`
+Exécuté avant chaque gate individuel.
+**Usage typique :** Préparation données, nettoyage cache.
+
+### `afterEach`
+Exécuté après chaque gate individuel.
+**Usage typique :** Collecte métriques, nettoyage temporaire.
+
+### `afterAll`
+Exécuté une fois après tous les gates.
+**Usage typique :** Cleanup infrastructure, archivage logs.
+
+## Configuration Execution
+
+### Timeouts
+
+```yaml
+execution:
+  hook_timeout_ms: 180000  # Timeout global par hook (3 min)
+```
+
+**Priorité des timeouts :**
+1. Timeout individuel du hook
+2. `hook_timeout_ms` global
+3. Défaut : 180000ms (3 minutes)
+
+### Gestion d'Échecs
+
+```yaml
+execution:
+  on_failure: stop     # Arrêt immédiat si échec
+  on_failure: continue # Poursuite malgré les échecs
+```
+
+**Comportements :**
+- **`stop`** : Premier échec → arrêt complet
+- **`continue`** : Échecs → warnings, poursuite workflow
+
+### Fichier Compose
+
+```yaml
+execution:
+  compose_file: "docker-compose.yml"  # Défaut: services.yml
+```
+
+## Exemples Concrets
+
+### Setup API + Base de Données
+
+```yaml
+hooks:
+  beforeAll:
+    - compose: up
+    - wait_on: "localhost:5432"
+      method: tcp
+      timeout: 30000
+    - wait_on: "http://localhost:3000/healthz"
+      method: http
+      timeout: 45000
+    - run: "npm run db:migrate"
+  
+  afterAll:
+    - run: "npm run db:cleanup"
+    - compose: down
+```
+
+### Tests avec Services Externes
+
+```yaml
+hooks:
+  beforeAll:
+    - run: "docker pull redis:alpine"
+    - run: "docker run -d --name qa360-redis -p 6379:6379 redis:alpine"
+    - wait_on: "localhost:6379"
+      method: tcp
+  
+  afterAll:
+    - run: "docker stop qa360-redis"
+    - run: "docker rm qa360-redis"
+```
+
+### Préparation Données par Gate
+
+```yaml
+hooks:
+  beforeEach:
+    - run: "npm run test:seed"
+  
+  afterEach:
+    - run: "npm run test:cleanup"
+```
+
+## Sécurité et Limitations
+
+### Redaction Automatique
+- Secrets automatiquement masqués dans les logs
+- Variables d'environnement sensibles protégées
+- Outputs des commandes filtrés
+
+### Commandes Dangereuses
+**Détection automatique :**
+- `rm -rf`
+- `sudo rm`
+- `format`
+- `mkfs`
+
+**Recommandation :** Éviter les commandes destructives.
+
+### Resource Limits
+
+```yaml
+execution:
+  limits:
+    cpu: "1"      # Limite CPU (optionnel)
+    memory: "1Gi" # Limite mémoire (optionnel)
+```
+
+**Note :** Limites appliquées uniquement en environnement conteneurisé.
+
+## Troubleshooting
+
+### Hook Timeout
+```
+❌ Hook failed after 180000ms (timeout)
+```
+**Solution :** Augmenter `timeout` individuel ou `hook_timeout_ms`.
+
+### Compose File Not Found
+```
+QH001: Compose file not found: services.yml
+```
+**Solution :** Créer le fichier ou définir `compose_file`.
+
+### Service Not Ready
+```
+❌ HTTP endpoint http://localhost:3000/healthz not ready after 30000ms
+```
+**Solutions :**
+- Augmenter timeout `wait_on`
+- Vérifier health check du service
+- Ajouter délai dans le service
+
+### Docker Not Available
+```
+QH004: Docker not available
+```
+**Solution :** Installer Docker Desktop ou démarrer le daemon.
+
+## Bonnes Pratiques
+
+### 1. Timeouts Appropriés
+```yaml
+# Services légers
+- wait_on: "http://localhost:3000/healthz"
+  timeout: 15000
+
+# Bases de données
+- wait_on: "localhost:5432"
+  timeout: 45000
+
+# Services complexes
+- compose: up
+  timeout: 120000
+```
+
+### 2. Idempotence
+```yaml
+# ✅ Bon : idempotent
+- compose: up
+- run: "mkdir -p /tmp/qa360"
+
+# ❌ Éviter : non-idempotent
+- run: "docker run -d redis"  # Peut échouer si déjà lancé
+```
+
+### 3. Cleanup Garanti
+```yaml
+afterAll:
+  - compose: down  # Toujours nettoyer
+  - run: "rm -rf /tmp/qa360-*"
+```
+
+### 4. Health Checks Robustes
+```yaml
+# ✅ Endpoint dédié
+- wait_on: "http://localhost:3000/healthz"
+
+# ❌ Endpoint métier (peut être lent)
+- wait_on: "http://localhost:3000/api/users"
+```
+
+## Intégration CI/CD
+
+### GitHub Actions
+```yaml
+- name: Run QA360 with hooks
+  run: |
+    qa360 run --pack pack.yml
+    
+- name: Upload artifacts
+  uses: actions/upload-artifact@v4
+  with:
+    path: .qa360/runs/
+```
+
+### Variables d'Environnement
+```yaml
+hooks:
+  beforeAll:
+    - run: "echo $CI_COMMIT_SHA > version.txt"
+    
+environment:
+  CI_COMMIT_SHA: "${{ github.sha }}"
+```
+
+Les hooks QA360 Phase 3 offrent une orchestration robuste et sécurisée pour des workflows de test complexes avec infrastructure éphémère.

package/docs/llm-providers.md

@@ -0,0 +1,419 @@
+# LLM Providers - QA360 AI Architecture
+
+QA360 supports multiple LLM providers with automatic fallback. This ensures your AI-powered test generation always works, even if one provider is unavailable.
+
+## Overview
+
+The AI module uses a **fallback chain** to automatically select the best available provider:
+
+```
+Ollama (local) → OpenAI → Anthropic → Mock (testing)
+```
+
+### Provider Priority
+
+| Priority | Provider | Type | Cost | Latency |
+|----------|----------|------|------|----------|
+| 1st | Ollama | Local | Free | Medium |
+| 2nd | OpenAI | Cloud | $$$ | Low |
+| 3rd | Anthropic | Cloud | $$$ | Low |
+| 4th | Mock | Local | Free | Instant |
+
+## Quick Start
+
+### Automatic Provider Selection
+
+```typescript
+import { createLLMProvider } from '@qa360/core';
+
+// Automatically selects the first available provider
+const provider = await createLLMProvider();
+
+// Generate code
+const response = await provider.generate({
+  prompt: 'Write a test for login API',
+  systemPrompt: 'You are a test generation expert',
+  maxTokens: 2000
+});
+
+console.log(response.content);
+```
+
+### Force a Specific Provider
+
+```typescript
+import { createLLMProvider } from '@qa360/core';
+
+// Prefer OpenAI, fall back to others if unavailable
+const provider = await createLLMProvider({
+  preferred: 'openai'
+});
+```
+
+### Skip a Provider
+
+```typescript
+import { createLLMProvider } from '@qa360/core';
+
+// Skip Ollama, go directly to cloud providers
+const provider = await createLLMProvider({
+  skip: ['ollama']
+});
+```
+
+## Provider Configuration
+
+### Ollama (Local - Default)
+
+Ollama is the preferred provider for local-first, free AI inference.
+
+**Environment Variables:**
+```bash
+export OLLAMA_BASE_URL="http://localhost:11434"  # Optional
+export OLLAMA_MODEL="deepseek-coder"              # Optional
+```
+
+**Setup:**
+```bash
+# Install Ollama
+curl -fsSL https://ollama.com/install.sh | sh
+
+# Pull a model
+ollama pull deepseek-coder
+
+# Start Ollama server
+ollama serve
+```
+
+**Code:**
+```typescript
+import { createOllamaProvider } from '@qa360/core';
+
+const provider = createOllamaProvider({
+  baseUrl: 'http://localhost:11434',
+  model: 'deepseek-coder'
+});
+
+const available = await provider.isAvailable();
+console.log('Ollama available:', available);
+```
+
+### OpenAI (Cloud)
+
+OpenAI provides GPT-4 and other powerful models via API.
+
+**Environment Variables:**
+```bash
+export OPENAI_API_KEY="sk-..."  # Required
+export OPENAI_BASE_URL="https://api.openai.com/v1"  # Optional
+export OPENAI_MODEL="gpt-4"  # Optional
+```
+
+**Supported Models:**
+- `gpt-4` - Most capable
+- `gpt-4-turbo` - Faster, cheaper
+- `gpt-4o` - Latest GPT-4 Omni
+- `gpt-4o-mini` - Smaller, faster
+- `gpt-3.5-turbo` - Budget option
+
+**Code:**
+```typescript
+import { createOpenAIProvider } from '@qa360/core';
+
+const provider = createOpenAIProvider({
+  apiKey: 'sk-...',
+  model: 'gpt-4'
+});
+```
+
+### Anthropic (Cloud)
+
+Anthropic provides Claude models with strong coding capabilities.
+
+**Environment Variables:**
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."  # Required
+export ANTHROPIC_BASE_URL="https://api.anthropic.com"  # Optional
+export ANTHROPIC_MODEL="claude-3-5-sonnet-20241022"  # Optional
+```
+
+**Supported Models:**
+- `claude-3-5-sonnet-20241022` - Best for code
+- `claude-3-5-sonnet-20240620` - Previous Sonnet
+- `claude-3-opus-20240229` - Most capable
+- `claude-3-haiku-20240307` - Fastest
+
+**Code:**
+```typescript
+import { createAnthropicProvider } from '@qa360/core';
+
+const provider = createAnthropicProvider({
+  apiKey: 'sk-ant-...',
+  model: 'claude-3-5-sonnet-20241022'
+});
+```
+
+### Mock (Testing)
+
+The Mock provider returns predefined responses without making network calls. Useful for testing and development.
+
+```typescript
+import { createMockProvider } from '@qa360/core';
+
+const provider = createMockProvider({
+  delay: 50,  // Simulate latency in ms
+  responses: {
+    'test': 'Mock response for test'
+  }
+});
+```
+
+## Advanced Usage
+
+### Check Provider Availability
+
+```typescript
+import { getProviderStatus, detectBestProvider } from '@qa360/core';
+
+// Check all providers
+const status = await getProviderStatus();
+console.log(status);
+// { ollama: true, openai: false, anthropic: false, mock: true }
+
+// Detect best available
+const best = await detectBestProvider();
+console.log('Best provider:', best);
+// 'ollama'
+```
+
+### Custom Fallback Chain
+
+```typescript
+import { createLLMProvider } from '@qa360/core';
+
+// Custom order: Anthropic → OpenAI → Mock
+const provider = await createLLMProvider({
+  chain: ['anthropic', 'openai', 'mock']
+});
+```
+
+### Streaming Responses
+
+```typescript
+const provider = await createLLMProvider();
+
+// Stream tokens as they arrive
+for await (const chunk of provider.stream({
+  prompt: 'Write a test function',
+  maxTokens: 500
+})) {
+  process.stdout.write(chunk);
+}
+```
+
+### Count Tokens
+
+```typescript
+const provider = await createLLMProvider();
+
+const text = 'Your prompt here...';
+const tokens = provider.countTokens(text);
+
+console.log(`Approximate tokens: ${tokens}`);
+```
+
+## Error Handling
+
+All providers throw specific errors that you can catch:
+
+```typescript
+import { OpenAIError, AnthropicError, OllamaError } from '@qa360/core';
+
+try {
+  const response = await provider.generate({ prompt: 'test' });
+} catch (error) {
+  if (error instanceof OpenAIError) {
+    console.error('OpenAI error:', error.message);
+    console.error('Details:', error.details);
+  } else if (error instanceof AnthropicError) {
+    console.error('Anthropic error:', error.message);
+  } else {
+    console.error('Unknown error:', error);
+  }
+}
+```
+
+## CLI Integration
+
+The AI module is integrated into QA360 CLI commands:
+
+```bash
+# Test AI connection
+qa360 doctor
+
+# Generate tests using AI
+qa360 ask --prompt "Write tests for login API" --output tests/
+
+# Check Ollama status
+qa360 ollama test
+```
+
+## Best Practices
+
+### 1. Use Ollama for Local Development
+
+Ollama provides free, local inference. It's ideal for:
+- Development environments
+- CI/CD pipelines
+- Sensitive data (no external API calls)
+
+### 2. Set Fallback API Keys for Production
+
+Configure cloud API keys as fallback:
+```bash
+# .env
+OLLAMA_MODEL=deepseek-coder
+OPENAI_API_KEY=sk-...  # Fallback
+ANTHROPIC_API_KEY=sk-ant-...  # Fallback
+```
+
+### 3. Use Mock for Testing
+
+The Mock provider ensures deterministic tests:
+```typescript
+const mockProvider = createMockProvider({
+  responses: {
+    'generate login test': 'it("should login", () => { ... })'
+  }
+});
+```
+
+### 4. Handle Provider Failures Gracefully
+
+```typescript
+const provider = await createLLMProvider();
+const available = await provider.isAvailable();
+
+if (!available) {
+  console.warn('Primary provider unavailable, using fallback');
+}
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   QA360 AI Module                        │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  ┌──────────────┐       ┌──────────────┐              │
+│  │   Provider   │       │   Provider   │              │
+│  │   Factory    │───────│   Fallback   │              │
+│  └──────────────┘       └──────────────┘              │
+│         │                       │                       │
+│         ▼                       ▼                       │
+│  ┌──────────────┐       ┌──────────────┐              │
+│  │   Ollama     │       │   OpenAI     │              │
+│  │  Provider    │       │  Provider    │              │
+│  └──────────────┘       └──────────────┘              │
+│         │                       │                       │
+│         ▼                       ▼                       │
+│  ┌──────────────┐       ┌──────────────┐              │
+│  │  Anthropic   │       │    Mock      │              │
+│  │  Provider    │       │  Provider    │              │
+│  └──────────────┘       └──────────────┘              │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Reference
+
+### LLMProvider Interface
+
+```typescript
+interface LLMProvider {
+  name: string;                    // Provider name
+  models: string[];                // Supported models
+
+  generate(request: GenerationRequest): Promise<GenerationResponse>;
+  stream?(request: GenerationRequest): AsyncIterable<string>;
+  countTokens(text: string): number;
+  isAvailable(): Promise<boolean>;
+}
+
+interface GenerationRequest {
+  prompt: string;
+  systemPrompt?: string;
+  maxTokens?: number;
+  temperature?: number;
+}
+
+interface GenerationResponse {
+  content: string;
+  usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  model: string;
+  finishReason: 'stop' | 'length' | 'content_filter';
+}
+```
+
+### ProviderFactoryConfig
+
+```typescript
+interface ProviderFactoryConfig {
+  preferred?: 'ollama' | 'openai' | 'anthropic' | 'mock';
+  chain?: Array<'ollama' | 'openai' | 'anthropic' | 'mock'>;
+  skip?: Array<'ollama' | 'openai' | 'anthropic' | 'mock'>;
+
+  ollama?: { baseUrl?: string; model?: string; timeout?: number };
+  openai?: { apiKey?: string; baseURL?: string; model?: string };
+  anthropic?: { apiKey?: string; baseURL?: string; model?: string };
+  mock?: { delay?: number; responses?: Record<string, string> };
+}
+```
+
+## Troubleshooting
+
+### Ollama Not Available
+
+```bash
+# Check Ollama is running
+curl http://localhost:11434/api/tags
+
+# Start Ollama
+ollama serve
+
+# Pull a model
+ollama pull deepseek-coder
+```
+
+### OpenAI/Anthropic API Errors
+
+```bash
+# Verify API key
+echo $OPENAI_API_KEY
+
+# Test API key
+curl https://api.openai.com/v1/models \
+  -H "Authorization: Bearer $OPENAI_API_KEY"
+```
+
+### Provider Selection Issues
+
+```typescript
+// Debug provider selection
+import { getProviderStatus } from '@qa360/core';
+
+const status = await getProviderStatus();
+console.table(status);
+```
+
+## See Also
+
+- [Ollama Documentation](https://ollama.com/docs)
+- [OpenAI API Reference](https://platform.openai.com/docs/api-reference)
+- [Anthropic API Reference](https://docs.anthropic.com/claude/reference)
+- [AI Test Generation](./ai-generation.md)