DiffCatcher

🎯 Principais Recursos

• Descoberta de Repositórios: Varre recursivamente diretórios em busca de repositórios Git com filtros configuráveis
• Rastreamento de Estado: Captura estado pré/pós-pull com hashes de commit, mensagens e detecção de sujeira
• Geração de Diffs: Criação automática de diffs N vs N-1 e históricos com manifesto de arquivos
• Extração de Elementos: Analisa diffs para identificar funções, estruturas, classes, importações e mais em mais de 10 linguagens
• Trechos de Código: Extrai código completo antes/depois com detecção de limites e janelas de contexto
• Marcação de Segurança: 18 padrões de segurança incorporados (criptografia, autenticação, segredos, injeção SQL, XSS, etc.)
• Relatórios em Múltiplos Formatos: Saídas JSON, Markdown, texto e SARIF com visão geral de segurança entre repositórios
• Modo Diff de Branch: Diferença entre quaisquer duas referências (branches, tags, commits) em um único repositório — ideal para revisões de PR
• Desempenho: Processamento paralelo com barras de progresso, cache LRU e modo incremental

Por que não usar apenas bash?

Um one-liner como ls | while read line; do git -C "$line" diff HEAD~1 HEAD || true; done mostra apenas diffs brutos. DiffCatcher adiciona descoberta recursiva, extração de elementos de código, detecção de padrões de segurança, saída SARIF para CI/CD, processamento paralelo e agregação de segurança entre repositórios. Veja a comparação completa abaixo.

📋 Índice

• Instalação
• Início Rápido
• Uso
  • Varredura Básica
  • Modos de Pull
  • Opções de Extração
  • Marcação de Segurança
  • Arquivo de Configuração
  • Sistema de Plugins
  • Modo Diff de Branch (Revisão de PR)
  • Saída SARIF
  • Recursos Avançados
• Estrutura do Relatório
• Configuração
• Arquitetura
• Testes
• Documentação
• Contribuindo

🚀 Instalação

A Partir do Código Fonte

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

Requisitos

• Rust 1.70+
• Git 2.0+

⚡ Início Rápido

# Varre todos os repositórios em um diretório (apenas fetch, sem modificações)
diffcatcher ~/projects

# Atualiza com pull e gera relatório de segurança
diffcatcher ~/projects --pull -o ./report

# Diferença entre duas branches em um único repositório (modo revisão de PR)
diffcatcher ./my-repo --diff main..feature/auth -o ./pr-report

# Gera saída SARIF para GitHub Code Scanning
diffcatcher ~/projects --summary-format sarif,json -o ./report

# Simulação para ver o que seria varrido
diffcatcher ~/projects --dry-run

# Varredura rápida com 8 trabalhadores paralelos
diffcatcher ~/projects -j 8 --quiet

📖 Uso

Varredura Básica

# Varre com configurações padrão (apenas fetch)
diffcatcher <ROOT_DIR>

# Diretório de saída personalizado
diffcatcher ~/projects -o ./my-report

# Inclui repositórios aninhados e segue links simbólicos
diffcatcher ~/projects --nested --follow-symlinks

# Pula diretórios ocultos
diffcatcher ~/projects --skip-hidden

Modos de Pull

# Apenas fetch (padrão - sem alterações na árvore de trabalho)
diffcatcher ~/projects

# Realmente puxa alterações
diffcatcher ~/projects --pull

# Força pull com stash/pop para repositórios sujos
diffcatcher ~/projects --pull --force-pull

# Usa estratégia rebase
diffcatcher ~/projects --pull --pull-strategy rebase

# Pula fetch/pull completamente (apenas diffs históricos)
diffcatcher ~/projects --no-pull

Opções de Extração

# Pula extração de elementos (apenas diffs brutos)
diffcatcher ~/projects --no-summary-extraction

# Extrai elementos mas pula trechos de código
diffcatcher ~/projects --no-snippets

# Ajusta contexto e limites dos trechos
diffcatcher ~/projects --snippet-context 10 --max-snippet-lines 300

# Limita elementos por diff
diffcatcher ~/projects --max-elements 1000

Marcação de Segurança

# Pula marcação de segurança
diffcatcher ~/projects --no-security-tags

# Inclui arquivos de teste na análise de segurança
diffcatcher ~/projects --include-test-security

# Usa padrões de segurança personalizados
diffcatcher ~/projects --security-tags-file ./custom-patterns.json

Arquivo de Configuração

DiffCatcher pode carregar automaticamente a configuração local do projeto a partir de:

• <ROOT_DIR>/.diffcatcher.toml (padrão)
• um arquivo personalizado via --config <FILE>
• desabilitado com --no-config

Exemplo:

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

As flags da linha de comando ainda sobrescrevem os valores de configuração quando definidas explicitamente.

Sistema de Plugins

DiffCatcher suporta dois tipos de plugins:

• Plugins de padrões de segurança via --security-plugin-file <FILE> (repetível)
• Plugins de extratores via --extractor-plugin-file <FILE> (repetível)

O formato do plugin de segurança corresponde ao JSON de --security-tags-file (version, mode, tags).

Formato do plugin de extrator:

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

Modo Diff de Branch (Revisão de PR)

# Diferença entre duas branches em um único repositório
diffcatcher ./my-repo --diff main..feature/auth

# Diferença entre commits específicos
diffcatcher ./my-repo --diff abc123..def456

# Diferença com saída SARIF para integração CI
diffcatcher ./my-repo --diff origin/main..HEAD --summary-format sarif -o ./pr-report

A flag --diff BASE..HEAD pula a descoberta de repositórios e fetch/pull — ela difere diretamente duas referências (branches, tags ou SHAs de commit) e executa o pipeline completo de extração + marcação de segurança no resultado.

Saída SARIF

# Gera SARIF junto com outros formatos
diffcatcher ~/projects --summary-format sarif,json,md

# Apenas SARIF para upload em CI/CD
diffcatcher ~/projects --summary-format sarif -o ./report