DiffCatcher

🎯 Características Principales

• Descubrimiento de repositorios: Escanea directorios recursivamente en busca de repos Git con filtros configurables
• Seguimiento de estado: Captura el estado previo/posterior a pull con hashes de commits, mensajes y detección de cambios sin commit
• Generación de diferencias: Creación automática de diferencias N vs N-1 e históricas con manifiestos de archivos
• Extracción de elementos: Analiza diferencias para identificar funciones, estructuras, clases, importaciones y más en más de 10 lenguajes
• Fragmentos de código: Extrae código completo antes/después con detección de límites y ventanas de contexto
• Etiquetado de seguridad: 18 patrones de seguridad integrados (crypto, auth, secretos, inyección SQL, XSS, etc.)
• Informes multi-formato: Salidas JSON, Markdown, texto y SARIF con resumen de seguridad entre repositorios
• Modo de diferencia entre ramas: Diferencia dos referencias (ramas, tags, commits) en un solo repositorio — ideal para revisiones de PR
• Rendimiento: Procesamiento paralelo con barras de progreso, caché LRU y modo incremental

¿Por qué no solo usar bash?

Una línea como ls | while read line; do git -C "$line" diff HEAD~1 HEAD || true; done solo muestra diferencias en bruto. DiffCatcher añade descubrimiento recursivo, extracción de elementos de código, detección de patrones de seguridad, salida SARIF para CI/CD, procesamiento paralelo y agregación de seguridad entre repositorios. Ver comparación completa más abajo.

📋 Tabla de Contenidos

• Instalación
• Inicio Rápido
• Uso
  • Escaneo Básico
  • Modos de Pull
  • Opciones de Extracción
  • Etiquetado de Seguridad
  • Archivo de Configuración
  • Sistema de Plugins
  • Modo de Diferencia entre Ramas (Revisión de PR)
  • Salida SARIF
  • Funcionalidades Avanzadas
• Estructura del Informe
• Configuración
• Arquitectura
• Pruebas
• Documentación
• Contribuciones

🚀 Instalación

Desde Código Fuente

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

Requisitos

• Rust 1.70+
• Git 2.0+

⚡ Inicio Rápido

# Escanear todos los repositorios en un directorio (solo fetch, sin modificaciones)
diffcatcher ~/projects

# Obtener actualizaciones y generar informe de seguridad
diffcatcher ~/projects --pull -o ./report

# Diferencia dos ramas en un solo repositorio (modo revisión de PR)
diffcatcher ./my-repo --diff main..feature/auth -o ./pr-report

# Generar salida SARIF para GitHub Code Scanning
diffcatcher ~/projects --summary-format sarif,json -o ./report

# Ejecución en seco para ver qué se escanearía
diffcatcher ~/projects --dry-run

# Escaneo rápido con 8 trabajadores en paralelo
diffcatcher ~/projects -j 8 --quiet

📖 Uso

Escaneo Básico

# Escanear con configuración por defecto (solo fetch)
diffcatcher <ROOT_DIR>

# Directorio de salida personalizado
diffcatcher ~/projects -o ./my-report

# Incluir repositorios anidados y seguir enlaces simbólicos
diffcatcher ~/projects --nested --follow-symlinks

# Omitir directorios ocultos
diffcatcher ~/projects --skip-hidden

Modos de Pull

# Solo fetch (por defecto - sin cambios en el árbol de trabajo)
diffcatcher ~/projects

# Realizar pull de cambios
diffcatcher ~/projects --pull

# Forzar pull con stash/pop para repositorios sucios
diffcatcher ~/projects --pull --force-pull

# Usar estrategia rebase
diffcatcher ~/projects --pull --pull-strategy rebase

# Omitir totalmente fetch/pull (solo diferencias históricas)
diffcatcher ~/projects --no-pull

Opciones de Extracción

# Omitir extracción de elementos (solo diferencias en bruto)
diffcatcher ~/projects --no-summary-extraction

# Extraer elementos pero omitir fragmentos de código
diffcatcher ~/projects --no-snippets

# Ajustar contexto de fragmentos y límites
diffcatcher ~/projects --snippet-context 10 --max-snippet-lines 300

# Limitar elementos por diferencia
diffcatcher ~/projects --max-elements 1000

Etiquetado de Seguridad

# Omitir etiquetado de seguridad
diffcatcher ~/projects --no-security-tags

# Incluir archivos de prueba en el análisis de seguridad
diffcatcher ~/projects --include-test-security

# Usar patrones de seguridad personalizados
diffcatcher ~/projects --security-tags-file ./custom-patterns.json

Archivo de Configuración

DiffCatcher puede cargar automáticamente la configuración local del proyecto desde:

• <ROOT_DIR>/.diffcatcher.toml (por defecto)
• un archivo personalizado mediante --config <FILE>
• deshabilitado con --no-config

Ejemplo:

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

Los indicadores CLI aún anulan los valores de configuración cuando se establecen explícitamente.

Sistema de Plugins

DiffCatcher soporta dos tipos de plugins:

• Plugins de patrones de seguridad mediante --security-plugin-file <FILE> (repetible)
• Plugins de extractores mediante --extractor-plugin-file <FILE> (repetible)

El formato del plugin de seguridad coincide con el JSON de --security-tags-file (version, mode, tags).

Formato del plugin extractor:

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

Modo de Diferencia entre Ramas (Revisión de PR)

# Diferencia dos ramas en un solo repositorio
diffcatcher ./my-repo --diff main..feature/auth

# Diferencia commits específicos
diffcatcher ./my-repo --diff abc123..def456

# Diferencia con salida SARIF para integración en CI
diffcatcher ./my-repo --diff origin/main..HEAD --summary-format sarif -o ./pr-report

El indicador --diff BASE..HEAD omite el descubrimiento de repositorios y fetch/pull — diferencia directamente dos referencias (ramas, tags o SHAs de commit) y ejecuta el proceso completo de extracción + etiquetado de seguridad sobre el resultado.

Salida SARIF

# Generar SARIF junto con otros formatos
diffcatcher ~/projects --summary-format sarif,json,md