Metadata-Version: 2.4
Name: safepatch
Version: 0.1.1
Summary: Ferramenta CLI de auditoria e comparação de pacotes Java/compactados (.jar, .war, .zip) com detecção de conflitos e diff descompilado
Author-email: Matheus Braga <contato@matheusbraga.dev>
Maintainer-email: Matheus Braga <contato@matheusbraga.dev>
License: MIT
Project-URL: Homepage, https://matheusbraga.dev
Project-URL: Repository, https://github.com/matheusbraga-dev/safepatch
Project-URL: Issues, https://github.com/matheusbraga-dev/safepatch/issues
Project-URL: Documentation, https://github.com/matheusbraga-dev/safepatch#readme
Keywords: java,jar,war,zip,diff,decompiler,cfr,patch,audit,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown

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

[![PyPI version](https://img.shields.io/pypi/v/safepatch.svg)](https://pypi.org/project/safepatch/)
[![Python Versions](https://img.shields.io/pypi/pyversions/safepatch.svg)](https://pypi.org/project/safepatch/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

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)

```bash
pip install safepatch
```

### Via Código-Fonte (Desenvolvimento)

```bash
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:

```bash
python -m unittest discover tests
```

---

## 💻 Guia de Uso

### 1. Comparação Básica

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

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

**Exemplo de saída no terminal:**
```text
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`:

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

**Exemplo de saída com diff Java descompilado e colorido:**
```diff
[~] 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:

```bash
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:

```bash
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:

```bash
# 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:

```bash
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

```text
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:

```bash
python -m unittest discover tests
```

Para rodar em modo detalhado (verbose):

```bash
python -m unittest discover tests -v
```

---

## 📄 Licença

Este projeto é disponibilizado sob a licença [MIT](https://opensource.org/licenses/MIT).
