DiffCatcher

🎯 Caratteristiche Principali

• Scoperta Repository: Scansiona ricorsivamente directory alla ricerca di repo Git con filtri configurabili
• Tracciamento Stato: Cattura stato pre/post-pull con hash dei commit, messaggi e rilevamento di directory sporche
• Generazione Diff: Creazione automatica di diff N vs N-1 e storici con manifest dei file
• Estrazione Elementi: Analizza i diff per identificare funzioni, struct, classi, import e altro in oltre 10 linguaggi
• Frammenti di Codice: Estrae codice completo prima/dopo con rilevamento dei confini e finestre di contesto
• Marcatura di Sicurezza: 18 pattern di sicurezza integrati (crittografia, autenticazione, segreti, SQL injection, XSS, ecc.)
• Report Multi-Formato: Output JSON, Markdown, testo e SARIF con panoramica sicurezza cross-repo
• Modalità Diff tra Branch: Crea diff tra due qualsiasi riferimenti (branch, tag, commit) in un singolo repo — ideale per revisioni PR
• Prestazioni: Elaborazione parallela con barre di progresso, caching LRU e modalità incrementale

Perché non usare semplicemente bash?

Un one-liner come ls | while read line; do git -C "$line" diff HEAD~1 HEAD || true; done mostra solo diff grezzi. DiffCatcher aggiunge scoperta ricorsiva, estrazione di elementi di codice, rilevamento di pattern di sicurezza, output SARIF per CI/CD, elaborazione parallela e aggregazione della sicurezza tra repository. Vedi confronto completo più sotto.

📋 Indice

• Installazione
• Avvio Rapido
• Utilizzo
  • Scansione Base
  • Modalità Pull
  • Opzioni di Estrazione
  • Marcatura di Sicurezza
  • File di Configurazione
  • Sistema di Plugin
  • Modalità Diff tra Branch (Revisione PR)
  • Output SARIF
  • Funzionalità Avanzate
• Struttura del Report
• Configurazione
• Architettura
• Test
• Documentazione
• Contributi

🚀 Installazione

Da Codice Sorgente

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

Requisiti

• Rust 1.70+
• Git 2.0+

⚡ Avvio Rapido

# Scansiona tutti i repo in una directory (solo fetch, nessuna modifica)
diffcatcher ~/projects

# Esegui pull e genera report di sicurezza
diffcatcher ~/projects --pull -o ./report

# Crea diff tra due branch in un singolo repo (modalità revisione PR)
diffcatcher ./my-repo --diff main..feature/auth -o ./pr-report

# Genera output SARIF per GitHub Code Scanning
diffcatcher ~/projects --summary-format sarif,json -o ./report

# Esecuzione a secco per vedere cosa verrebbe scansionato
diffcatcher ~/projects --dry-run

# Scansione veloce con 8 lavoratori paralleli
diffcatcher ~/projects -j 8 --quiet

📖 Utilizzo

Scansione Base

# Scansiona con impostazioni predefinite (solo fetch)
diffcatcher <ROOT_DIR>

# Directory di output personalizzata
diffcatcher ~/projects -o ./my-report

# Includi repo nidificati e segui i link simbolici
diffcatcher ~/projects --nested --follow-symlinks

# Salta directory nascoste
diffcatcher ~/projects --skip-hidden

Modalità Pull

# Solo fetch (predefinito - nessuna modifica al working tree)
diffcatcher ~/projects

# Esegui effettivamente il pull delle modifiche
diffcatcher ~/projects --pull

# Forza pull con stash/pop per repo sporchi
diffcatcher ~/projects --pull --force-pull

# Usa strategia rebase
diffcatcher ~/projects --pull --pull-strategy rebase

# Salta fetch/pull completamente (solo diff storici)
diffcatcher ~/projects --no-pull

Opzioni di Estrazione

# Salta estrazione elementi (solo diff grezzi)
diffcatcher ~/projects --no-summary-extraction

# Estrai elementi ma salta i frammenti di codice
diffcatcher ~/projects --no-snippets

# Regola contesto e limiti dei frammenti
diffcatcher ~/projects --snippet-context 10 --max-snippet-lines 300

# Limita elementi per diff
diffcatcher ~/projects --max-elements 1000

Marcatura di Sicurezza

# Salta marcatura di sicurezza
diffcatcher ~/projects --no-security-tags

# Includi file di test nell'analisi di sicurezza
diffcatcher ~/projects --include-test-security

# Usa pattern di sicurezza personalizzati
diffcatcher ~/projects --security-tags-file ./custom-patterns.json

File di Configurazione

DiffCatcher può caricare automaticamente la configurazione locale del progetto da:

• <ROOT_DIR>/.diffcatcher.toml (predefinito)
• un file personalizzato tramite --config <FILE>
• disabilitato con --no-config

Esempio:

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"]

I flag CLI sovrascrivono comunque i valori di configurazione quando esplicitamente impostati.

Sistema di Plugin

DiffCatcher supporta due tipi di plugin:

• Plugin di pattern di sicurezza tramite --security-plugin-file <FILE> (ripetibile)
• Plugin di estrazione tramite --extractor-plugin-file <FILE> (ripetibile)

Il formato del plugin di sicurezza corrisponde al JSON di --security-tags-file (version, mode, tags).

Formato del plugin di estrazione:

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

Modalità Diff tra Branch (Revisione PR)

# Crea diff tra due branch in un singolo repo
diffcatcher ./my-repo --diff main..feature/auth

# Crea diff tra commit specifici
diffcatcher ./my-repo --diff abc123..def456

# Crea diff con output SARIF per integrazione CI
diffcatcher ./my-repo --diff origin/main..HEAD --summary-format sarif -o ./pr-report

Il flag --diff BASE..HEAD salta la scoperta del repository e il fetch/pull — crea direttamente il diff tra due riferimenti (branch, tag o SHA di commit) ed esegue l'intera pipeline di estrazione + marcatura di sicurezza sul risultato.

Output SARIF

# Genera SARIF insieme ad altri formati
diffcatcher ~/projects --summary-format sarif,json,md

# Solo SARIF per upload CI/CD
diffcatcher ~/projects --summary-format sarif -o ./report