DiffCatcher

<!-- donation:eth:start -->
<div align="center">

## Soutenir le développement

Si ce projet vous aide dans votre travail, soutenez sa maintenance continue et ses nouvelles fonctionnalités.

**Portefeuille de dons ETH**  
`0x11282eE5726B3370c8B480e321b3B2aA13686582`

<a href="https://etherscan.io/address/0x11282eE5726B3370c8B480e321b3B2aA13686582">
  <img src="https://raw.githubusercontent.com/teycir/diffcatcher/HEAD/publiceth.svg" alt="Code QR de don Ethereum" width="220" />
</a>

_Scannez le code QR ou copiez l'adresse du portefeuille ci-dessus._

</div>
<!-- donation:eth:end -->

<div align="center">
  <img src="https://raw.githubusercontent.com/teycir/diffcatcher/HEAD/assets/logo.svg" alt="Logo DiffCatcher" width="100%" />

  <br/>

  [![Rust](https://img.shields.io/badge/rust-1.70+-orange.svg)](https://www.rust-lang.org/)
  [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  [![Security](https://img.shields.io/badge/security-focused-green.svg)](docs/security.md)

  <p><b>Un outil CLI en Rust qui découvre récursivement les dépôts Git, capture les changements d'état, génère des diffs, extrait des éléments de code avec des extraits complets et produit des rapports axés sur la sécurité pour les workflows de révision de code et d'audit.</b></p>
</div>

<br/>

## 🎯 Fonctionnalités clés

- **Découverte de dépôts** : Parcourir récursivement les répertoires à la recherche de dépôts Git avec des filtres configurables
- **Suivi d'état** : Capturer l'état avant/après un pull avec les hashs de commit, les messages et la détection de répertoire modifié (dirty)
- **Génération de diffs** : Création automatique de diffs N vs N-1 et historiques avec des manifestes de fichiers
- **Extraction d'éléments** : Analyser les diffs pour identifier les fonctions, structures, classes, importations, etc. dans plus de 10 langages
- **Extraits de code** : Extraire le code complet avant/après avec détection des limites et fenêtres de contexte
- **Marquage de sécurité** : 18 motifs de sécurité intégrés (crypto, auth, secrets, injection SQL, XSS, etc.)
- **Rapports multi-formats** : Sorties JSON, Markdown, texte et **SARIF** avec une vue d'ensemble de la sécurité inter-dépôts
- **Mode Diff de branches** : Différencier deux références (branches, tags, commits) dans un seul dépôt — idéal pour les revues de PR
- **Performances** : Traitement parallèle avec barres de progression, cache LRU et mode incrémental

> **Pourquoi ne pas simplement utiliser bash ?**
> 
> Une ligne de commande comme `ls | while read line; do git -C "$line" diff HEAD~1 HEAD || true; done` n'affiche que les diffs bruts.
> DiffCatcher ajoute la découverte récursive, l'extraction d'éléments de code, la détection de motifs de sécurité,
> la sortie SARIF pour CI/CD, le traitement parallèle et l'agrégation de sécurité inter-dépôts.
> Voir la [comparaison complète](#comparaison-avec-bash) ci-dessous.

## 📋 Table des matières

- [Installation](#installation)
- [Démarrage rapide](#démarrage-rapide)
- [Utilisation](#utilisation)
  - [Analyse de base](#analyse-de-base)
  - [Modes de pull](#modes-de-pull)
  - [Options d'extraction](#options-dextraction)
  - [Marquage de sécurité](#marquage-de-sécurité)
  - [Fichier de configuration](#fichier-de-configuration)
  - [Système de plugins](#système-de-plugins)
  - [Mode Diff de branches (Revue de PR)](#mode-diff-de-branches-revue-de-pr)
  - [Sortie SARIF](#sortie-sarif)
  - [Fonctionnalités avancées](#fonctionnalités-avancées)
- [Structure du rapport](#structure-du-rapport)
- [Configuration](#configuration)
- [Architecture](#architecture)
- [Tests](#tests)
- [Documentation](#documentation)
- [Contribuer](#contribuer)

## 🚀 Installation

### Depuis les sources

```bash
git clone https://github.com/Teycir/DiffCatcher.git
cd DiffCatcher
cargo build --release
./target/release/diffcatcher --help
```

### Prérequis

- Rust 1.70+
- Git 2.0+

## ⚡ Démarrage rapide

```bash
# Analyser tous les dépôts dans un répertoire (fetch uniquement, aucune modification)
diffcatcher ~/projects

# Récupérer les mises à jour et générer un rapport de sécurité
diffcatcher ~/projects --pull -o ./report

# Différencier deux branches dans un seul dépôt (mode revue de PR)
diffcatcher ./my-repo --diff main..feature/auth -o ./pr-report

# Générer une sortie SARIF pour GitHub Code Scanning
diffcatcher ~/projects --summary-format sarif,json -o ./report

# Simulation pour voir ce qui serait analysé
diffcatcher ~/projects --dry-run

# Analyse rapide avec 8 workers en parallèle
diffcatcher ~/projects -j 8 --quiet
```

## 📖 Utilisation

### Analyse de base

```bash
# Analyser avec les paramètres par défaut (fetch uniquement)
diffcatcher <ROOT_DIR>

# Répertoire de sortie personnalisé
diffcatcher ~/projects -o ./my-report

# Inclure les dépôts imbriqués et suivre les liens symboliques
diffcatcher ~/projects --nested --follow-symlinks

# Ignorer les répertoires cachés
diffcatcher ~/projects --skip-hidden
```

### Modes de pull

```bash
# Fetch uniquement (par défaut - aucune modification de l'arbre de travail)
diffcatcher ~/projects

# Effectuer effectivement un pull des changements
diffcatcher ~/projects --pull

# Forcer le pull avec stash/pop pour les dépôts modifiés
diffcatcher ~/projects --pull --force-pull

# Utiliser la stratégie rebase
diffcatcher ~/projects --pull --pull-strategy rebase

# Ignorer complètement le fetch/pull (diffs historiques uniquement)
diffcatcher ~/projects --no-pull
```

### Options d'extraction

```bash
# Ignorer l'extraction d'éléments (diffs bruts uniquement)
diffcatcher ~/projects --no-summary-extraction

# Extraire les éléments mais ignorer les extraits de code
diffcatcher ~/projects --no-snippets

# Ajuster le contexte et les limites des extraits
diffcatcher ~/projects --snippet-context 10 --max-snippet-lines 300

# Limiter les éléments par diff
diffcatcher ~/projects --max-elements 1000
```

### Marquage de sécurité

```bash
# Ignorer le marquage de sécurité
diffcatcher ~/projects --no-security-tags

# Inclure les fichiers de test dans l'analyse de sécurité
diffcatcher ~/projects --include-test-security

# Utiliser des motifs de sécurité personnalisés
diffcatcher ~/projects --security-tags-file ./custom-patterns.json
```

### Fichier de configuration

DiffCatcher peut charger automatiquement une configuration locale au projet depuis :

- `<ROOT_DIR>/.diffcatcher.toml` (par défaut)
- un fichier personnalisé via `--config <FILE>`
- désactivé avec `--no-config`

Exemple :

```toml
output = "reports-local"
no_pull = true
history_depth = 2
summary_formats = ["json", "txt"]
no_security_tags = false

[plugins]
security_pattern_files = ["plugins/security-extra.json"]
extractor_files = ["plugins/extractors.json"]
```

Les options de ligne de commande ont toujours priorité sur les valeurs du fichier de configuration lorsqu'elles sont explicitement définies.

### Système de plugins

DiffCatcher prend en charge deux types de plugins :

- Plugins de motifs de sécurité via `--security-plugin-file <FILE>` (répétable)
- Plugins d'extraction via `--extractor-plugin-file <FILE>` (répétable)

Le format du plugin de sécurité correspond au JSON de `--security-tags-file` (`version`, `mode`, `tags`).

Format du plugin d'extraction :

```json
{
  "version": 1,
  "extractors": [
    {
      "name": "policy-rule",
      "kind": "Config",
      "regex": "^policy\\s+([A-Za-z_][A-Za-z0-9_]*)"
    }
  ]
}
```

### Mode Diff de branches (Revue de PR)

```bash
# Différencier deux branches dans un seul dépôt
diffcatcher ./my-repo --diff main..feature/auth

# Différencier des commits spécifiques
diffcatcher ./my-repo --diff abc123..def456

# Différencier avec sortie SARIF pour intégration CI
diffcatcher ./my-repo --diff origin/main..HEAD --summary-format sarif -o ./pr-report
```

Le flag `--diff BASE..HEAD` ignore la découverte de dépôts et le fetch/pull — il différencie directement deux références (branches, tags, ou SHAs de commit) et exécute le pipeline complet d'extraction et de marquage de sécurité sur le résultat.

### Sortie SARIF

```bash
# Générer SARIF en plus d'autres formats
diffcatcher ~/projects --summary-format sarif,json,md

# SARIF uniquement pour upload CI/CD
diffcatcher ~/projects --summary-format sarif -o ./report
```

Lorsque `sarif` est inclus dans `--summary-format`, un fichier `results.sarif` est écrit à la racine du rapport. Ce fichier suit la norme [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) et s'intègre avec GitHub Code Scanning, VS Code SARIF Viewer, Azure DevOps et d'autres outils compatibles SARIF.

### Fonctionnalités avancées

```bash
# Mode incrémental (ignorer les dépôts inchangés)
diffcatcher ~/projects --incremental -o ./report

# Filtrer par motif de branche
diffcatcher ~/projects --branch-filter "main"

# Ajuster la profondeur historique
diffcatcher ~/projects --history-depth 5

# Sortie JSON pour CI/CD
diffcatcher ~/projects --quiet --json > result.json

# Sortie verbose avec les chemins découverts
diffcatcher ~/projects --verbose
```

## 📁 Structure du rapport

```
<report_dir>/
├── summary.json                    # Résumé global
├── summary.md                      # Résumé en Markdown
├── results.sarif                   # Sortie SARIF 2.1.0 (quand --summary-format sarif)
├── security_overview.json          # Agrégation de sécurité inter-dépôts
├── security_overview.md
├── <repo-name>/
│   ├── status.json                 # État du dépôt
│   ├── pull_log.txt
│   └── diffs/
│       ├── diff_N_vs_N-1.patch     # Diff unifié brut
│       ├── changes_N_vs_N-1.txt    # Manifeste des fichiers
│       ├── summary_N_vs_N-1.json   # Extraction d'éléments
│       ├── summary_N_vs_N-1.md
│       └── snippets/
│           ├── 001_validate_token_ADDED.rs
│           ├── 002_check_permissions_BEFORE.rs
│           ├── 002_check_permissions_AFTER.rs
│           └── 002_check_permissions.diff
└── ...
```

## ⚙️ Configuration

### Options CLI

| Option | Valeur par défaut | Description |
|--------|-------------------|-------------|
| `-o, --output` | `./reports/<timestamp>` | Répertoire de sortie du rapport |
| `-j, --parallel` | `4` | Traitement concurrent des dépôts |
| `-t, --timeout` | `120` | Délai d’expiration des opérations Git (secondes) |
| `-d, --history-depth` | `2` | Commits historiques à différencier |
| `--snippet-context` | `5` | Lignes de contexte autour des modifications |
| `--max-snippet-lines` | `200` | Nombre maximal de lignes par extrait |
| `--max-elements` | `500` | Nombre maximal d'éléments par diff |
| `--diff` | — | Différencier deux références dans un seul dépôt (`BASE..HEAD`) |
| `--summary-format` | `json,md` | Formats de sortie : `json`, `md`, `txt`, `sarif` |

Consultez `diffcatcher --help` pour toutes les options.

### Motifs de sécurité personnalisés

Créez un fichier JSON avec des motifs personnalisés :

```json
{
  "version": 1,
  "mode": "extend",
  "tags": [
    {
      "tag": "pii-handling",
      "description": "Traitement des données personnelles",
      "severity": "High",
      "patterns": ["ssn", "social_security", "passport"]
    }
  ]
}
```

Utilisez avec `--security-tags-file ./patterns.json`

## 🏗️ Architecture

```
src/
├── cli.rs              # Analyse des arguments
├── scanner.rs          # Découverte de dépôts
├── git/                # Opérations Git
│   ├── commands.rs     # Wrappers Git
│   ├── state.rs        # Capture d'état
│   ├── diff.rs         # Génération de diffs
│   └── file_retrieval.rs
├── extraction/         # Extraction d'éléments
│   ├── parser.rs       # Analyseur de diff unifié
│   ├── elements.rs     # Détection d'éléments
│   ├── snippets.rs     # Extraction d'extraits de code
│   ├── boundary.rs     # Suivi des accolades/indentations
│   └── languages/      # Motifs spécifiques aux langages
├── security/           # Marquage de sécurité
│   ├── tagger.rs       # Correspondance de motifs
│   ├── patterns.rs     # Motifs intégrés
│   └── overview.rs     # Agrégation inter-dépôts
└── report/             # Génération de rapports
    ├── writer.rs       # Structure de répertoire
    ├── json.rs         # Sérialisation JSON
    ├── sarif.rs        # Sortie SARIF 2.1.0
    ├── markdown.rs     # Formatage Markdown
    └── snippet_writer.rs
```

## Comparaison avec Bash

Une simple ligne de commande bash peut lister les diffs :

```bash
ls | while read line; do git -C "$line" diff HEAD~1 HEAD || true; done
```

Cela fonctionne pour des vérifications rapides, mais DiffCatcher ajoute des capacités significatives :

| Capacité | Ligne de commande Bash | DiffCatcher |
|----------|------------------------|-------------|
| **Découverte récursive** | Éléments de premier niveau uniquement | Dépôts imbriqués, liens symboliques, filtres |
| **Suivi d'état** | Aucun | Hashs de commit, détection de répertoire modifié, logs de pull |
| **Compréhension du code** | Diff brut uniquement | Extrait fonctions/structures/classes dans plus de 10 langages |
| **Extraits de code** | Aucun | Code complet avant/après avec fenêtres de contexte |
| **Analyse de sécurité** | Aucune | 18 motifs intégrés (auth, crypto, secrets, SQLi, XSS) |
| **Formats de sortie** | Terminal uniquement | JSON, Markdown, **SARIF** (GitHub Code Scanning) |
| **Vue inter-dépôts** | Par dépôt uniquement | Rapport de sécurité agrégé sur tous les dépôts |
| **Performances** | Séquentiel | Workers parallèles, cache LRU, mode incrémental |
| **Intégration CI/CD** | Aucune | Upload SARIF vers GitHub/Azure DevOps |
| **Gestion des erreurs** | Suppression `|| true` | Gestion correcte des erreurs avec journalisation détaillée |
| **Gestion des chemins** | Échoue sur les espaces | Gère tous les noms de chemins correctement |
| **Contexte historique** | `HEAD~1` fixe | Profondeur configurable, suivi d'état |

**La ligne de commande bash fait environ 100 octets. DiffCatcher est un outil d'audit axé sur la sécurité avec extraction complète des éléments de code.**

## 🧪 Tests

```bash
# Exécuter tous les tests
cargo test

# Exécuter une suite de tests spécifique
cargo test security_tagger

# Exécuter avec sortie
cargo test -- --nocapture
```

La couverture des tests inclut :
- Tests unitaires pour l'extraction, le marquage de sécurité, la détection des limites
- Tests d'intégration pour la capture d'état, la génération de diffs, les rapports
- Tests de fichiers dorés pour la précision de l'extraction
- Tests de cas limites (HEAD détaché, dépôts nus, commit unique)

### Benchmarks de performance

```bash
# Compiler les binaires de benchmark
cargo bench --no-run

# Exécuter le harnais de benchmark
cargo bench --bench core_bench
```

La source du benchmark se trouve dans `benches/core_bench.rs` et mesure le débit de l'analyseur/extraction.

### CI/CD

Les workflows GitHub Actions sont inclus :

- `.github/workflows/ci.yml` : vérification du format, clippy, tests, construction des benchmarks
- `.github/workflows/release.yml` : empaquetage de version basé sur les tags et publication de version GitHub

## 📚 Documentation

### Documentation du projet
- [Plan.md](https://github.com/teycir/diffcatcher/blob/main/Plan.md) - Spécification complète (v1.2)
- [Roadmap.md](https://github.com/teycir/diffcatcher/blob/main/Roadmap.md) - Feuille de route de mise en œuvre et progrès
- Référence des motifs de sécurité (voir `src/security/patterns.rs`)

### Documentation du code
Tous les modules incluent une documentation en ligne complète. Modules clés :
- `src/extraction/parser.rs` - Analyseur de diff unifié avec extraction de blocs
- `src/extraction/elements.rs` - Détection d'éléments de code sensible au langage
- `src/extraction/snippets.rs` - Extraction complète d'extraits de code avec détection des limites
- `src/security/tagger.rs` - Moteur de correspondance de motifs de sécurité
- `src/git/commands.rs` - Wrappers d'opérations Git

Générer la documentation complète de l'API :
```bash
cargo doc --open
```

## 🏷️ Tags

`#rust` `#git` `#security` `#code-review` `#diff-analysis` `#static-analysis` `#devops` `#cli-tool` `#audit` `#vulnerability-detection` `#code-quality` `#snippet-extraction` `#parallel-processing` `#security-scanning`

## 🤝 Contribuer

Les contributions sont les bienvenues ! Veuillez :
1. Forker le dépôt
2. Créer une branche de fonctionnalité
3. Ajouter des tests pour les nouvelles fonctionnalités
4. Assurez-vous que `cargo test` passe
5. Soumettre une pull request

## 📄 Licence

Licence MIT - voir le fichier [LICENSE](https://github.com/teycir/diffcatcher/blob/main/LICENSE) pour plus de détails

## 📧 Contact

- **Auteur** : Teycir Ben Soltane
- **Email** : [email protected]
- **Site web** : teycirbensoltane.tn

## 🔗 Liens

- [Dépôt GitHub](https://github.com/Teycir/DiffCatcher)
- [Suivi des problèmes](https://github.com/Teycir/DiffCatcher/issues)
- [Changelog](https://github.com/teycir/diffcatcher/blob/main/CHANGELOG.md)