push-guardian 1.0.0

package/developper_utils.md

@@ -0,0 +1,119 @@
+# **Documentation Développeur push-guardian**
+
+push-guardian est un outil CLI basé sur Node.js pour la validation automatisée de la qualité du code et la gestion des hooks Git. Ce document explique son architecture, ses composants et comment l'étendre.
+
+## **Vue d'ensemble de l'architecture**
+
+push-guardian suit une architecture modulaire avec une séparation claire des préoccupations :
+
+- **Couche CLI** : Analyse des commandes et interaction utilisateur
+- **Couche Core** : Logique métier et moteurs de validation
+- **Couche Hooks** : Intégration Git et validation des contraintes
+- **Couche Utils** : Utilitaires partagés
+
+## **Composants principaux**
+
+Point d'entrée CLI
+Le point d'entrée principal est index.js, qui utilise Commander.js pour définir les commandes. Les commandes sont chargées dynamiquement depuis command.
+
+Structure d'exemple de commande :
+
+```js
+module.exports = {
+    name: 'example',
+    description: 'Commande exemple',
+    options: [{ flags: '-v, --verbose', description: 'Sortie verbeuse' }],
+    action: async (options) => {
+        // Logique de commande
+    }
+};
+```
+
+Gestion de la configuration
+La configuration est gérée par configManager.js, qui charge/sauvegarde `push-guardian.config.json.`
+
+Fonctions clés :
+
+- **loadConfig()** : Charge la configuration avec des valeurs par défaut
+- **saveConfig(config)** : Sauvegarde la configuration mise à jour
+
+Moteur de validation
+La logique de validation principale est dans validator.js, qui orchestre les exécutions ESLint et les validations de hooks.
+
+Moteur de contraintes
+Les contraintes sont gérées par constraintEngine.js, un système flexible pour valider les messages et les branches.
+
+Pour ajouter une nouvelle contrainte :
+
+```js
+this.constraints.set('newConstraint', (value, param) => {
+    // Logique de validation
+    return value.length > param;
+});
+this.errorMessages.newConstraint = (param) => `Le message doit être plus long que ${param} caractères`;
+```
+Intégration des hooks Git
+Les hooks sont définis dans constrains.js, supportant les hooks commit-msg, post-checkout et pre-push.
+
+Flux de validation des hooks :
+
+1. Charger la config pour le hook
+2. Appliquer les contraintes via constraintEngine.validate()
+3. Quitter avec une erreur si la validation échoue
+
+Pour ajouter un nouveau langage :
+
+```js
+const LANGUAGE_TOOLS = {
+    'Nouveau Langage': {
+        packages: ['eslint-plugin-newlang'],
+        setup: setupNewLanguage
+    }
+};
+```
+
+Utilitaires
+Utilitaires partagés incluent :
+
+- **exec-wrapper.js** : Wrapper d'exécution de commandes asynchrones
+- **chalk-wrapper.js** : Sortie colorisée avec fallback
+
+## **Tests**
+Les tests sont dans unit utilisant Jest. Lancez avec `npm test`.
+
+Exemple de test pour le moteur de contraintes :
+
+```js
+describe('Moteur de Contraintes', () => {
+    test('valide correctement', () => {
+        // Logique de test
+    });
+});
+```
+## **Étendre push-guardian**
+
+Ajouter une nouvelle commande
+
+1. Créer un nouveau fichier dans command
+2. Exporter l'objet commande comme montré ci-dessus
+3. Il sera automatiquement chargé par index.js
+
+Ajouter un nouveau type de hook
+
+1. Mettre à jour constrains.js pour gérer le nouveau hook
+2. Ajouter le support de configuration dans configManager.js
+
+Contraintes personnalisées
+Utilisez constraintEngine.addConstraint() pour enregistrer de nouveaux validateurs.
+
+## **Gestion des erreurs**
+Les erreurs sont centralisées dans errorCMD.js, qui formate et quitte avec les traces de pile.
+
+## **Workflow de développement**
+
+1. Installer les dépendances : npm install
+2. Lancer les tests : npm test
+3. Lier pour le développement : npm link
+4. Construire/vérifier : Utiliser ESLint via npx push-guardian validate
+
+Pour plus de détails, voir le `README.md` principal et `TECHNO.md`.

package/docker-compose.yml

@@ -0,0 +1,41 @@
+services:
+  push-guardian:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: push-guardian
+    user: "${UID:-1000}:${GID:-1000}"
+    volumes:
+      # Monter le projet à valider
+      - ./:/workspace
+      # Monter la config git
+      - ~/.gitconfig:/home/push-guardian/.gitconfig:ro
+    working_dir: /workspace
+    environment:
+      - NODE_ENV=production
+      - TOKEN=${TOKEN:-}
+      - GITLAB_TOKEN=${GITLAB_TOKEN:-}
+      - AZURE_DEVOPS_URL=${AZURE_DEVOPS_URL:-}
+      - AZURE_DEVOPS_TOKEN=${AZURE_DEVOPS_TOKEN:-}
+    command: validate
+
+  # Service pour tests
+  test:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    volumes:
+      - ./:/app
+      - /app/node_modules
+    command: npm test
+
+  # Service pour couverture
+  coverage:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    volumes:
+      - ./:/app
+      - /app/node_modules
+      - ./coverage:/app/coverage
+    command: npm run test:coverage

package/docs/PLUGINS.md

@@ -0,0 +1,223 @@
+# Système de Plugins push-guardian v2
+
+Le système de plugins push-guardian v2 permet d'étendre les fonctionnalités via des commandes personnalisées.
+
+## Caractéristiques
+
+- **Commandes uniquement** : Les plugins enregistrent des commandes CLI (pas de hooks Git)
+- **Gestion locale** : Plugins créés et gérés localement dans le dossier `plugins/`
+- **Enable/Disable** : Activation/désactivation sans suppression
+
+## Utilisation
+
+### Lister les plugins installés
+
+```bash
+push-guardian plugin list
+```
+
+### Activer/Désactiver un plugin
+
+```bash
+push-guardian plugin enable <nom-du-plugin>
+push-guardian plugin disable <nom-du-plugin>
+```
+
+### Lister les commandes disponibles
+
+```bash
+push-guardian plugin commands
+```
+
+### Exécuter une commande de plugin
+
+```bash
+push-guardian plugin run <nom-du-plugin> <commande> [args...]
+```
+
+Exemple avec le plugin d'exemple :
+```bash
+push-guardian plugin run example-plugin hello
+push-guardian plugin run example-plugin greet "John"
+push-guardian plugin run example-plugin info
+```
+
+## Créer un plugin
+
+### Structure du plugin
+
+```
+mon-plugin/
+├── plugin.json
+└── index.js
+```
+
+### plugin.json
+
+```json
+{
+  "name": "mon-plugin",
+  "version": "1.0.0",
+  "description": "Description de mon plugin",
+  "author": "Votre Nom",
+  "main": "index.js",
+  "commands": ["ma-commande", "autre-commande"]
+}
+```
+
+### index.js
+
+```javascript
+const BasePlugin = require('../../src/core/plugins/basePlugin');
+const { getChalk } = require('../../src/utils/chalk-wrapper');
+const chalk = getChalk();
+
+class MonPlugin extends BasePlugin {
+    constructor(manifest) {
+        super(manifest);
+        this.setupCommands();
+    }
+
+    setupCommands() {
+        this.registerCommand('ma-commande', async (args, options) => {
+            console.log(chalk.green('Ma commande s\'exécute!'));
+            return 'Résultat de la commande';
+        }, {
+            description: 'Description de ma commande',
+            args: []
+        });
+
+        this.registerCommand('autre-commande', async (args, options) => {
+            const param = args[0];
+            console.log(chalk.cyan(`Paramètre reçu: ${param}`));
+            return `Traité: ${param}`;
+        }, {
+            description: 'Commande avec un argument',
+            args: ['parametre']
+        });
+    }
+}
+
+module.exports = MonPlugin;
+```
+
+## Configuration locale
+
+Le fichier `.push-guardian-plugins.json` stocke la configuration locale :
+
+```json
+{
+  "plugins": {
+    "example-plugin": {
+      "path": "plugins/example-plugin",
+      "version": "1.0.0",
+      "enabled": true,
+      "installedAt": "2024-01-15T10:30:00.000Z"
+    }
+  }
+}
+```
+
+## Architecture
+
+```
+push-guardian
+│
+├── src/core/
+│   └── plugins/
+│       ├── basePlugin.js           # Classe de base
+│       ├── pluginRegistry.js       # Registre local
+│       └── pluginManager.js        # Gestionnaire d'exécution
+│
+├── src/cli/command/
+│   └── plugin.js                   # Commande CLI
+│
+└── plugins/                        # Plugins créés localement
+    └── example-plugin/
+        ├── plugin.json
+        └── index.js
+```
+
+## Notes importantes
+
+- Les plugins sont des **extensions de commandes** uniquement
+- Ils **ne s'exécutent pas automatiquement** lors des hooks Git
+- Utilisez `push-guardian plugin run <plugin> <commande>` pour les exécuter
+- La désactivation d'un plugin empêche l'exécution de ses commandes
+- Le manifest (`plugin.json`) est obligatoire et doit contenir : name, version, description, author, main
+- Les plugins sont créés localement dans le dossier `plugins/` à la racine du projet
+
+### BasePlugin
+
+Classe de base que tous les plugins doivent étendre.
+
+**Constructeur**
+- `constructor(manifest)` : Reçoit le manifest (plugin.json)
+
+**Méthodes**
+- `registerCommand(name, handler, options)` : Enregistre une commande
+  - `name` : Nom de la commande
+  - `handler` : Fonction async (args, options) => résultat
+  - `options.description` : Description de la commande
+  - `options.args` : Tableau des noms d'arguments
+  
+- `executeCommand(commandName, args, options)` : Exécute une commande
+- `getManifest()` : Retourne le manifest du plugin
+- `cleanup()` : Nettoie les ressources (appelé à la désinstallation)
+
+**Propriétés**
+- `name` : Nom du plugin
+- `version` : Version du plugin
+- `description` : Description du plugin
+- `author` : Auteur du plugin
+- `enabled` : État du plugin (actif/inactif)
+- `commands` : Map des commandes enregistrées
+
+## Configuration locale
+
+Le fichier `.push-guardian-plugins.json` stocke la configuration locale :
+
+```json
+{
+  "plugins": {
+    "example-plugin": {
+      "path": "example-plugin",
+      "version": "1.0.0",
+      "enabled": true,
+      "installedAt": "2024-01-15T10:30:00.000Z"
+    }
+  }
+}
+```
+
+## Architecture
+
+```
+push-guardian
+│
+├── src/core/
+│   ├── api/
+│   │   └── pluginApiClient.js      # Client API pour le dépôt
+│   └── plugins/
+│       ├── basePlugin.js           # Classe de base
+│       ├── pluginRegistry.js       # Registre local
+│       ├── pluginManager.js        # Gestionnaire d'exécution
+│       ├── pluginInstaller.js      # Installation/désinstallation
+│       └── pluginPublisher.js      # Publication
+│
+├── src/cli/command/
+│   └── plugin.js                   # Commande CLI
+│
+└── plugins/                        # Plugins installés
+    └── example-plugin/
+        ├── plugin.json
+        └── index.js
+```
+
+## Notes importantes
+
+- Les plugins sont des **extensions de commandes** uniquement
+- Ils **ne s'exécutent pas automatiquement** lors des hooks Git
+- Utilisez `push-guardian plugin run <plugin> <commande>` pour les exécuter
+- La désactivation d'un plugin empêche l'exécution de ses commandes
+- Le manifest (`plugin.json`) est obligatoire et doit contenir : name, version, description, author, main

package/docs/technical/architecture.md

@@ -0,0 +1,298 @@
+# Architecture push-guardian
+
+## Vue d'ensemble
+
+push-guardian est un outil de validation de code et de gestion de workflow Git structuré en modules indépendants.
+
+## Structure du projet
+
+```
+push-guardian/
+├── src/
+│   ├── cli/                    # Interface en ligne de commande
+│   │   ├── index.js           # Point d'entrée CLI
+│   │   ├── command/           # Commandes CLI
+│   │   └── install/           # Scripts d'installation
+│   ├── core/                  # Logique métier
+│   │   ├── cache/            # Système de cache
+│   │   ├── codeQualityTools/ # Outils de qualité de code
+│   │   ├── interactiveMenu/  # Menus interactifs
+│   │   ├── mirroring/        # Système de mirroring
+│   │   ├── performance/      # Analyse de performance
+│   │   ├── plugins/          # Système de plugins
+│   │   └── reviewApps/       # Review apps pour PR
+│   ├── hooks/                 # Hooks Git
+│   └── utils/                 # Utilitaires
+├── tests/                     # Tests unitaires
+└── docs/                      # Documentation
+
+```
+
+## Modules principaux
+
+### 1. CLI (Command Line Interface)
+
+Le module CLI fournit l'interface utilisateur en ligne de commande.
+
+**Fichiers clés:**
+- `src/cli/index.js` - Point d'entrée principal
+- `src/cli/command/*.js` - Commandes disponibles
+
+**Commandes disponibles:**
+- `config` - Gestion de la configuration
+- `install` - Installation des modules
+- `mirror` - Gestion du mirroring
+- `security` - Analyse de sécurité
+- `validate` - Validation du code
+- `plugin` - Gestion des plugins
+- `performance` - Analyse de performance
+
+### 2. Code Quality Tools
+
+Module de gestion de la qualité du code (ESLint, Prettier, etc.).
+
+**Composants:**
+- `configAnalyzer.js` - Analyse des configurations existantes
+- `configGenerator.js` - Génération de configurations
+- `configManager.js` - Gestion globale des configs
+- `fileDetector.js` - Détection de fichiers
+- `languageTools.js` - Outils par langage
+- `toolInstaller.js` - Installation d'outils
+
+### 3. Mirroring
+
+Système de synchronisation multi-plateformes (GitHub, GitLab, BitBucket, Azure).
+
+**Composants:**
+- `branchSynchronizer.js` - Synchronisation de branches
+- `generate.js` - Génération de workflows
+- `repoManager.js` - Gestion des dépôts
+- `syncManager.js` - Orchestration de la synchro
+
+### 4. Plugins
+
+Architecture modulaire permettant l'extension des fonctionnalités.
+
+**Composants:**
+- `basePlugin.js` - Classe de base pour plugins
+- `pluginRegistry.js` - Registre central
+- `pluginManager.js` - Gestionnaire de plugins
+
+**Hooks disponibles:**
+- `pre-validate` - Avant validation
+- `post-validate` - Après validation
+- `pre-commit` - Avant commit
+- `post-commit` - Après commit
+
+### 5. Performance
+
+Système d'analyse et de collecte de métriques de performance.
+
+**Composants:**
+- `metricsCollector.js` - Collecte de métriques
+- `performanceAnalyzer.js` - Analyse et rapports
+- `performanceReporter.js` - Génération de rapports
+
+### 6. Cache
+
+Système de cache multiniveau (mémoire + disque).
+
+**Composants:**
+- `cacheManager.js` - Gestionnaire principal
+- `cacheStrategy.js` - Stratégies (LRU, TTL)
+
+**Stratégies:**
+- LRU (Least Recently Used) - Cache en mémoire
+- TTL (Time To Live) - Cache avec expiration
+
+### 7. Review Apps
+
+Système de déploiement temporaire pour les Pull Requests.
+
+**Composants:**
+- `reviewAppManager.js` - Gestion des déploiements
+- `prIntegration.js` - Intégration GitHub/GitLab
+
+**Providers supportés:**
+- Local
+- Docker
+- Vercel
+- Netlify
+
+## Flux de données
+
+### Validation de code
+
+```
+Commit Git
+  ↓
+Hook pre-commit
+  ↓
+Validation push-guardian
+  ↓
+├─ Cache check
+├─ Plugin hooks (pre-validate)
+├─ ESLint/Prettier
+├─ Tests
+├─ Contraintes
+└─ Plugin hooks (post-validate)
+  ↓
+Métriques de performance
+  ↓
+Résultat (success/failure)
+```
+
+### Mirroring
+
+```
+Push sur GitHub
+  ↓
+GitHub Action (workflow)
+  ↓
+SyncManager
+  ↓
+├─ BranchSynchronizer
+├─ RepoManager
+└─ API calls (GitLab, etc.)
+  ↓
+Synchronisation complète
+```
+
+### Review Apps
+
+```
+Pull Request créée
+  ↓
+PR Integration détecte la PR
+  ↓
+ReviewAppManager
+  ↓
+├─ Création du déploiement
+├─ Build de l'app
+├─ Déploiement (Vercel/Netlify/Docker)
+└─ Commentaire sur PR avec URL
+  ↓
+Review App accessible
+```
+
+## Configuration
+
+### Fichier principal: `push-guardian.config.json`
+
+```json
+{
+  "codeQualityTools": {
+    "enabled": true,
+    "tools": ["JavaScript (ESLint)", "TypeScript (TypeScript ESLint)"]
+  },
+  "mirroring": {
+    "enabled": true,
+    "platforms": {
+      "github": { "enabled": true },
+      "gitlab": { "enabled": true }
+    }
+  },
+  "plugins": {
+    "enabled": true,
+    "paths": ["./plugins"]
+  },
+  "cache": {
+    "enabled": true,
+    "strategy": "LRU",
+    "maxSize": 200
+  },
+  "performance": {
+    "enabled": true,
+    "collectMetrics": true
+  }
+}
+```
+
+## Variables d'environnement
+
+```bash
+# Tokens
+GITHUB_TOKEN=xxx
+GITLAB_TOKEN=xxx
+BITBUCKET_TOKEN=xxx
+
+# Mirroring
+push-guardian_MIRROR_SOURCE_PLATFORM=github
+push-guardian_MIRROR_TARGET_PLATFORM=gitlab
+
+# Review Apps
+VERCEL_TOKEN=xxx
+NETLIFY_AUTH_TOKEN=xxx
+
+# Performance
+push-guardian_ENABLE_METRICS=true
+```
+
+## Extensibilité
+
+### Créer un plugin
+
+```javascript
+const BasePlugin = require('./src/core/plugins/basePlugin');
+
+class MyPlugin extends BasePlugin {
+    constructor() {
+        super('my-plugin', '1.0.0');
+    }
+
+    async initialize() {
+        this.registerHook('pre-validate', async (data) => {
+            console.log('Pre-validation personnalisée');
+            return data;
+        });
+    }
+}
+
+module.exports = MyPlugin;
+```
+
+### Enregistrer le plugin
+
+```bash
+npx push-guardian plugin --load ./plugins
+```
+
+## Tests
+
+```bash
+# Tous les tests
+npm test
+
+# Tests avec couverture
+npm test -- --coverage
+
+# Tests d'un module spécifique
+npm test -- tests/unit/configAnalyzer.test.js
+```
+
+## Performance
+
+Le système de performance collecte automatiquement:
+- Durée des validations
+- Durée des hooks
+- Durée du linting
+- Taux de succès
+
+Analyse:
+```bash
+npx push-guardian performance --analyze
+```
+
+## Sécurité
+
+- Tokens stockés dans `.env` (non versionné)
+- Validation des entrées utilisateur
+- Sandboxing des plugins
+- Permissions limitées pour les hooks
+
+## Limites connues
+
+- Cache disque limité à 1 Go par défaut
+- Review Apps limitées à 10 déploiements simultanés
+- Plugins ne peuvent pas modifier le core
+- Métriques conservées 30 jours maximum