🛡️ SafePatch (.jar / .war / .zip)

Uma ferramenta de linha de comando (CLI) em Python de alta performance para inspeção, auditoria e comparação de pacotes compactados (.jar, .war, .zip). Desenvolvida para detectar conflitos, arquivos alterados, adições e remoções entre versões de artefatos de release, patches e bibliotecas.

Zero dependências externas: construída exclusivamente com a biblioteca padrão do Python.

---

🚀 Funcionalidades

• ⚡ Leitura Otimizada em Streaming: Processa pacotes lendo blocos de 64KB sob demanda, permitindo analisar arquivos pesados com consumo mínimo de memória RAM.
• 🔒 Verificação de Integridade (SHA-256): Compara o hash SHA-256 de cada arquivo interno para garantir a detecção exata de modificações lógicas, mesmo quando as datas de modificação ou atributos forem alterados.
• 📊 Cálculo de Variação (Delta): Exibe a diferença de tamanho (em bytes, KB, MB) para cada arquivo modificado (ex: 1.81 KB → 2.39 KB | +602 B).
• ☕ Diff Descompilado no Estilo Git (-d / --diff):
  • Mostra as linhas adicionadas (+) e removidas (-) em arquivos modificados, novos e deletados.
  • Suporta arquivos de texto puro (XML, JSON, properties, YAML, SQL, código-fonte, etc.).
  • Descompilação Automática de Bytecode Java (.class): Descompila arquivos .class em código-fonte Java real e limpo (via CFR Decompiler integrado), permitindo ler métodos e classes sem ter que decifrar instruções de bytecode.
• 🎯 Filtro de Exclusão com Padrões Glob (-i / --ignorar): Permite ignorar metadados voláteis como META-INF/*, arquivos de documentação (*.md) ou logs.
• 📄 Múltiplos Formatos de Relatório:
  • Console (Terminal): Colorido via ANSI com modo compacto ou verboso (--verbose).
  • JSON (--json): Estruturado com metadados e totais, ideal para integrações e APIs.
  • Markdown (--markdown / --md): Tabelas e diffs prontas para documentação ou Pull Requests.
  • HTML (--html): Dashboard visual moderno, responsivo, com diffs embutidos e 100% autossuficiente (sem dependências externas).
• 🤖 Pronto para CI/CD (--fail-on-conflict): Retorna código de saída 2 se detectar arquivos conflitantes/modificados, permitindo travar esteiras de deploy indesejadas.

---

📋 Requisitos

• Python 3.8+ (compatível com Linux, macOS e Windows).
• Java JRE/JDK 8+ instalado no sistema (para descompilação de arquivos .class).

---

🛠️ Instalação

Via PyPI (Recomendado)

pip install safepatch

Via Código-Fonte (Desenvolvimento)

git clone https://github.com/matheusbraga-dev/safepatch.git
cd safepatch
pip install -e .

Para validar a integridade da instalação, execute a suíte de testes:

python -m unittest discover tests

---

💻 Guia de Uso

1. Comparação Básica

Para comparar dois pacotes .jar, .war ou .zip:

safepatch --base "caminho/para/versao_antiga.jar" --alvo "caminho/para/versao_nova.jar"

Exemplo de saída no terminal:

Iniciando varredura dos pacotes...
Lendo pacote base: versao_antiga.jar...
Lendo pacote alvo: versao_nova.jar...
Analisando diferenças e detectando conflitos...

=== RELATÓRIO DE COMPARAÇÃO DE PACOTES ===
Pacote Base: versao_antiga.jar
Pacote Alvo: versao_nova.jar
==========================================

Total Adicionados: 0
Total Removidos:   0
Total Modificados: 1
Total Inalterados: 7
------------------------------------------

[~] ARQUIVOS MODIFICADOS (Atenção - Possíveis Conflitos):
    br/com/mv/editor/dto/PaguObjetoDTO.class (1.81 KB → 2.39 KB | +602 B)

---

2. Visualizando Diferenças Detalhadas Estilo Git (--diff / -d)

Para inspecionar o código exato das alterações (linhas adicionadas + e removidas -), utilize a flag -d ou --diff:

safepatch --base "original/pacote.jar" --alvo "modificado/pacote.jar" --diff

Exemplo de saída com diff Java descompilado e colorido:

[~] ARQUIVOS MODIFICADOS (Atenção - Possíveis Conflitos):
    br/com/mv/editor/dto/PaguObjetoDTO.class (1.81 KB → 2.39 KB | +602 B)
diff --git a/br/com/mv/editor/dto/PaguObjetoDTO.class b/br/com/mv/editor/dto/PaguObjetoDTO.class
--- a/br/com/mv/editor/dto/PaguObjetoDTO.class
+++ b/br/com/mv/editor/dto/PaguObjetoDTO.class
@@ -53,4 +53,8 @@
         entity.setTpObjeto(this.getTpObjeto());
         return entity;
     }
+
+    public String getCdObjetoENome() {
+        return this.getCdObjeto() + " - " + this.getNmObjeto();
+    }
 }

Dica: O diff também é automaticamente incorporado aos relatórios exportados em Markdown e HTML quando a flag --diff for utilizada junto com --md ou --html. No PowerShell (Windows), para quebrar linhas em comandos utilize o caractere de acento grave (`) em vez da barra invertida (\).

---

3. Exportando Relatórios (JSON, Markdown e HTML)

Você pode gerar relatórios em um ou mais formatos simultaneamente:

safepatch --base "original/pacote.jar" \
          --alvo "modificado/pacote.jar" \
          --diff \
          --json relatorio.json \
          --md relatorio.md \
          --html relatorio.html

---

4. Ignorando Metadados ou Padrões Específicos

Para evitar falsos positivos gerados por manifests de build ou documentação:

safepatch --base "pacote_v1.jar" \
          --alvo "pacote_v2.jar" \
          -i "META-INF/*" \
          -i "*.properties"

---

5. Modo Verboso e Controle de Limite de Exibição

Por padrão, a CLI exibe no máximo 10 arquivos por categoria no console para evitar poluição. Para ver todos os arquivos:

# Exibe todos os arquivos no terminal sem paginação
safepatch --base "base.jar" --alvo "alvo.jar" --verbose

# Ou configure um limite personalizado (ex: 25 itens)
safepatch --base "base.jar" --alvo "alvo.jar" --limite 25

---

6. Integração Contínua (CI/CD)

Use a flag --fail-on-conflict para interromper scripts de automação se houver alterações inesperadas:

safepatch --base "base.jar" --alvo "alvo.jar" --fail-on-conflict

Códigos de Saída (Exit Codes):

Código	Significado
0	Sucesso (análise concluída sem conflitos críticos).
1	Erro de execução (arquivo não encontrado, ZIP corrompido, argumentos inválidos).
2	Conflito detectado (quando executado com a flag --fail-on-conflict).

---

📖 Referência de Parâmetros da CLI

Parâmetro	Tipo	Descrição
--base	string	Obrigatório. Caminho para o pacote base de referência.
--alvo	string	Obrigatório. Caminho para o pacote alvo a ser comparado.
-d, --diff	flag	Exibe a diferença detalhada do conteúdo estilo Git (linhas adicionadas e removidas em código Java legível).
-i, --ignorar	string	Padrão glob de arquivos a ignorar (ex: 'META-INF/*'). Pode ser repetido.
-v, --verbose	flag	Exibe a lista completa de arquivos no terminal sem limites.
--limite	int	Quantidade máxima de itens por categoria exibidos no terminal (padrão: 10).
--no-color	flag	Desativa a coloração ANSI na saída do console.
--json	string	Caminho do arquivo para salvar o relatório em formato JSON.
--md, --markdown	string	Caminho do arquivo para salvar o relatório em formato Markdown.
--html	string	Caminho do arquivo para salvar o relatório visual em HTML.
--fail-on-conflict	flag	Encerra com código 2 caso haja arquivos modificados.
-h, --help	flag	Exibe a mensagem de ajuda com todos os comandos disponíveis.

---

📁 Estrutura do Projeto

cli/
├── analisador/              # Módulo principal da aplicação
│   ├── __init__.py          # Exportação da API pública do módulo
│   ├── __main__.py          # Ponto de entrada para python -m analisador
│   ├── cli.py               # Controlador de linha de comando (CLI Controller)
│   ├── modelos.py           # Entidades de dados (ArquivoInfo, ArquivoModificadoInfo, Relatorio)
│   ├── models.py            # Alias de compatibilidade
│   ├── leitor.py            # Leitura streaming de .jar/.zip e cálculo de SHA-256
│   ├── comparador.py        # Motor de comparação de conjuntos e filtros
│   ├── diferenciador.py     # Motor de diff unificado com CFR Java Decompiler
│   ├── relatorio.py         # Apresentador do relatório para terminal com cores ANSI
│   └── exportadores.py      # Exportadores estruturados (JSON, Markdown, HTML)
├── tests/                   # Suíte de testes automatizados
│   ├── __init__.py
│   └── test_analisador.py   # Testes unitários com unittest
├── main.py                  # Ponto de entrada raiz
├── pyproject.toml           # Metadados e configuração de build do pacote PyPI
├── .gitignore               # Configurações de exclusão do Git
└── README.md                # Documentação completa do projeto

---

🧪 Executando os Testes

Para rodar todos os testes automatizados:

python -m unittest discover tests

Para rodar em modo detalhado (verbose):

python -m unittest discover tests -v

---

📄 Licença

Este projeto é disponibilizado sob a licença MIT.