Ce document explique comment développer, tester et contribuer au projet RepoLens.

• Rust : Version stable (1.74+ recommandée)

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

• Git : Pour la gestion de version
• Authentification GitHub (une des options suivantes) :
  • GITHUB_TOKEN : Variable d'environnement avec un token GitHub (recommandé depuis v1.2.0)
  • GitHub CLI (gh) : Installation via gh auth login (fallback automatique)

1. Cloner le repository

   git clone https://github.com/delfour-co/cli--repolens.git
   cd cli--repolens

2. Installer les dépendances

   cargo build

3. Vérifier l'installation

   cargo run -- --help

src/
├── main.rs              # Point d'entrée du CLI
├── lib.rs               # Exports de la bibliothèque
├── cli/                 # Commandes CLI
│   ├── commands/        # Implémentation des commandes (init, plan, apply, report, schema, compare, install_hooks)
│   └── output/          # Formats de sortie (terminal, JSON, SARIF, Markdown, HTML)
├── cache/               # Système de cache d'audit (invalidation par SHA256)
├── compare/             # Comparaison de rapports d'audit (score diff, régressions, améliorations)
├── config/              # Chargement et gestion de la configuration
│   └── presets/         # Presets de configuration (opensource, enterprise, strict)
├── hooks/               # Gestion des Git hooks (pre-commit, pre-push)
├── rules/               # Moteur d'audit et règles
│   ├── categories/      # Catégories de règles (secrets, files, docs, security, workflows, quality, licenses, dependencies, custom)
│   ├── patterns/        # Patterns de détection (secrets, etc.)
│   └── engine.rs        # Moteur d'exécution des règles
├── actions/             # Planification et exécution des actions
│   ├── planner.rs       # Planification des actions à partir des résultats
│   ├── executor.rs      # Exécution des actions (mode interactif supporté)
│   └── templates.rs     # Génération de fichiers à partir de templates
├── providers/           # Intégration avec les APIs externes
│   └── github.rs        # Provider GitHub (via gh CLI)
├── scanner/             # Scan du système de fichiers et Git
│   ├── filesystem.rs    # Scan du système de fichiers
│   └── git.rs           # Informations Git
└── utils/               # Utilitaires partagés
    └── prerequisites.rs # Vérification des prérequis (git, gh, etc.)

# Compilation en mode debug (rapide, avec symboles de debug)
cargo build

# Compilation en mode release (optimisé)
cargo build --release

# Vérification sans compilation
cargo check

# Lancer le CLI avec des arguments
cargo run -- --help
cargo run -- init
cargo run -- plan -vv
cargo run -- apply --dry-run
cargo run -- apply --interactive      # Mode interactif avec sélection d'actions
cargo run -- report --format json     # Rapport JSON
cargo run -- schema                   # Afficher le JSON Schema
cargo run -- compare --base-file a.json --head-file b.json  # Comparer deux rapports
cargo run -- install-hooks            # Installer les git hooks

# Avec logs détaillés
cargo run -- plan -vvv  # Trace level

# Lancer tous les tests
cargo test

# Tests avec output détaillé
cargo test -- --nocapture

# Tests d'un module spécifique
cargo test --lib rules

# Tests d'intégration
cargo test --test integration_test

RepoLens inclut une suite de benchmarks pour mesurer les performances :

# Lancer tous les benchmarks
cargo bench

# Benchmark spécifique
cargo bench --bench scanner_benchmark
cargo bench --bench rules_benchmark
cargo bench --bench parse_benchmark

Benchmarks disponibles :

Les résultats sont générés dans target/criterion/ avec des rapports HTML.

# Vérifier le formatage
cargo fmt --all -- --check

# Formater le code
cargo fmt --all

# Linter avec clippy
cargo clippy

# Clippy avec erreurs en warnings
cargo clippy -- -D warnings

# Vérification complète avant commit
cargo check && cargo fmt --all -- --check && cargo clippy -- -D warnings && cargo test

1. CLI (main.rs) : Parse les arguments et route vers la commande appropriée
2. Config : Charge la configuration depuis .repolens.toml ou utilise un preset
3. Scanner : Scanne le repository (fichiers, Git)
4. Rules Engine : Exécute les règles d'audit par catégorie
5. Action Planner : Génère un plan d'actions basé sur les résultats
6. Output : Formate et affiche les résultats selon le format demandé

1. Créer la règle dans la catégorie appropriée (src/rules/categories/)

   // src/rules/categories/ma_categorie.rs
   pub fn check_ma_regle(scanner: &Scanner, config: &Config) -> Vec<Finding> {
       let mut findings = Vec::new();
       // Logique de la règle
       findings
   }

2. Enregistrer la règle dans le moteur (src/rules/engine.rs)

   match category {
       "ma_categorie" => {
           findings.extend(ma_categorie::check_ma_regle(&scanner, &config)?);
       }
       // ...
   }

3. Ajouter la catégorie dans la configuration (src/config/loader.rs)

1. Créer l'action (src/actions/)

   pub struct MonAction {
       // Champs nécessaires
   }
   
   impl Action for MonAction {
       fn execute(&self) -> Result<ActionResult> {
           // Logique d'exécution
       }
   }

2. Ajouter la planification (src/actions/planner.rs)

   if condition {
       plan.add_action(Box::new(MonAction::new(...)));
   }

1. Créer le module de sortie (src/cli/output/)

   // src/cli/output/mon_format.rs
   pub fn format(results: &AuditResults) -> String {
       // Formatage
   }

2. Enregistrer dans le module (src/cli/output/mod.rs)

Le projet utilise tracing pour les logs. Niveaux de verbosité :

• -v : info level
• -vv : debug level
• -vvv : trace level

# Avec logs détaillés
cargo run -- plan -vv

# Avec variable d'environnement
RUST_LOG=debug cargo run -- plan

# Compiler avec symboles
cargo build

# Lancer avec GDB
gdb target/debug/repolens

# Ou avec LLDB (macOS)
lldb target/debug/repolens

Les patterns de secrets sont dans src/rules/patterns/secrets.rs. Pour tester :

# Créer un fichier de test avec un faux secret
echo "api_key = sk_test_1234567890abcdef" > test_secret.txt

# Lancer l'audit
cargo run -- plan

# Nettoyer
rm test_secret.txt

Créer un fichier .repolens.toml à la racine pour tester :

[general]
preset = "opensource"

[rules]
secrets = true
files = true
docs = true
security = true
workflows = true
quality = true

Les presets sont dans presets/ :

• opensource.toml : Standards open-source
• enterprise.toml : Sécurité entreprise
• strict.toml : Maximum de sécurité

Les tests d'intégration sont dans tests/integration_test.rs. Ils testent le CLI complet :

# Lancer les tests d'intégration
cargo test --test integration_test

1. Créer une branche

   git checkout -b feature/ma-feature

2. Développer et tester

   cargo check
   cargo test
   cargo fmt --all
   cargo clippy

3. Tester le CLI

   cargo run -- plan -vv
   cargo run -- apply --dry-run

4. Commit et Push

   git add .
   git commit -m "feat: ajout de ma feature"
   git push origin feature/ma-feature

5. Créer une Pull Request

• Utiliser cargo fmt avant chaque commit
• Respecter les conventions Rust (snake_case, etc.)
• Documenter les fonctions publiques avec ///

• Utiliser anyhow::Result pour les erreurs applicatives
• Utiliser thiserror pour les erreurs typées
• Toujours propager les erreurs avec ?

• Utiliser async/await pour les opérations I/O
• Éviter les allocations inutiles
• Profiler avec cargo flamegraph si nécessaire

• Écrire des tests unitaires pour chaque fonction publique
• Ajouter des tests d'intégration pour les workflows complets
• Tester les cas limites et les erreurs

# Nettoyer et reconstruire
cargo clean
cargo build

# Mettre à jour les dépendances
cargo update

# Vérifier les versions
cargo tree

# Lancer un test spécifique avec output
cargo test nom_du_test -- --nocapture

# Tests en parallèle (désactiver)
cargo test -- --test-threads=1

• Documentation Rust
• Rust Book
• Clap Documentation
• Tokio Documentation

Pour toute question ou problème :

• Ouvrir une issue sur GitHub
• Consulter la documentation dans le code
• Vérifier les exemples dans tests/