📦 Analisador de Pacotes (.jar / .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 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.).
  • Desmontagem de Bytecode Java (.class): Se o utilitário javap estiver instalado no sistema, desmonta automaticamente os arquivos .class e compara as assinaturas de métodos e atributos no estilo Git.
• 🎯 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 prontas para documentação ou Pull Requests.
  • HTML (--html): Dashboard visual moderno, responsivo 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).
• Nenhuma biblioteca externa necessária (pip install desnecessário).

---

🛠️ Instalação e Configuração

Clone o repositório ou copie os arquivos para sua máquina:

git clone https://github.com/matheusbraga-dev/safepatch.git
cd cli

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 ou .zip:

python main.py --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 conteúdo exato das alterações (linhas adicionadas + e removidas -), utilize a flag -d ou --diff:

python main.py --base "original/pacote.jar" \
               --alvo "modificado/pacote.jar" \
               --diff

Exemplo de saída com diff unificado 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
@@ -94,4 +94,20 @@
        0: aload_0
        1: invokevirtual #14                 // Method toEntity:()Lbr/com/mv/sma/entidades/PaguObjeto;
        4: areturn
+
+  public java.lang.String getCdObjetoENome();
+    Code:
+       0: new           #72                 // class java/lang/StringBuilder
+       3: dup
+       4: invokespecial #78                 // Method java/lang/StringBuilder."<init>":()V
+       7: aload_0
+       8: invokevirtual #96                 // Method br/com/mv/editor/dto/PaguObjetoDTO.getCdObjeto:()Ljava/lang/Long;
+      11: invokevirtual #82                 // Method java/lang/StringBuilder.append:(Ljava/lang/Object;)Ljava/lang/StringBuilder;
+      14: ldc_w         #108                // String  -
+      17: invokevirtual #86                 // Method java/lang/StringBuilder.append:(Ljava/lang/String;)Ljava/lang/StringBuilder;
+      20: aload_0
+      21: invokevirtual #102                // Method br/com/mv/editor/dto/PaguObjetoDTO.getNmObjeto:()Ljava/lang/String;
+      24: invokevirtual #86                 // Method java/lang/StringBuilder.append:(Ljava/lang/String;)Ljava/lang/StringBuilder;
+      27: invokevirtual #90                 // Method java/lang/StringBuilder.toString:()Ljava/lang/String;
+      30: areturn
 }

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 use 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:

python main.py --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:

python main.py --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
python main.py --base "base.jar" --alvo "alvo.jar" --verbose

# Ou configure um limite personalizado (ex: 25 itens)
python main.py --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:

python main.py --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).
-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
│   ├── 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 estilo Git e disassembly javap
│   ├── 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 da CLI (CLI Controller)
├── .gitignore               # Configurações de exclusão do Git
└── README.md                # Documentação 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.