qa360 2.2.1 → 2.2.13

package/docs/hooks.md

@@ -1,304 +0,0 @@
-# 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.