file-hasher

Uma ferramenta rápida e robusta para validar arquivos via SHA256 com interface TUI interativa e sistema de cache em disco.

Sobre

Este projeto é um utilitário em Rust que calcula e valida hashes SHA256 de arquivos de forma eficiente. Conta com uma interface TUI moderna (Terminal User Interface) baseada em ratatui, permitindo navegação intuitiva por teclado e validação em tempo real com barra de progresso. Possui um sistema de cache persistente que evita recalcular hashes de arquivos não modificados.

Funcionalidades

Interface TUI Interativa

• Seleção inicial de diretório: Ao iniciar, digite um caminho ou pressione Enter para usar o diretório atual.
• Navegação fluida:
  • ↑ / k: subir na lista
  • ↓ / j: descer na lista
  • Enter: abrir pasta ou validar arquivo
  • Backspace: voltar ao diretório pai
  • Ctrl+U: limpar campo de input (tela de seleção)
  • Q / q / Esc: sair
• Listagem do nível atual:
  • 📁 Pastas (ordenadas alfabeticamente primeiro)
  • 📄 Arquivos (com destaque: verde para válidos, vermelho para inválidos/erros)
• Validação com barra de progresso em tempo real: Mostra bytes lidos / total durante a validação.
• Resumo final: Ao sair, o terminal é restaurado e um resumo das validações realizadas é exibido.

Sistema de Cache Inteligente

• Cache centralizado em disco: Diretório ./cache/ (ao lado do binário)
• Validação automática: Cache é reutilizado apenas se tamanho e data de modificação coincidirem
• TTL de 7 dias: Entradas antigas são automaticamente removidas
• Limite de 2000 arquivos: Evita crescimento excessivo do cache
• Limpeza automática: Executada periodicamente durante o scan
• Preload na inicialização: Cache existente é carregado ao iniciar
• Estatísticas em tempo real: ok (cache hits), erros, tamanho do cache, hits da sessão

Background Scanning

• Scan recursivo automático: Ao selecionar um diretório, varre recursivamente toda a árvore em background
• Não bloqueia a UI: Você pode navegar e validar arquivos enquanto o scan ocorre
• Caching transparente: Todos os arquivos escaneados têm seus hashes salvos no cache
• Tratamento de erros: Arquivos com problemas de permissão ou leitura são registrados mas não interrompem o scan

Performance e Robustez

• Buffer de 64KB para leitura eficiente de arquivos grandes.
• Validação assíncrona (thread separada) para não travar a interface.
• Scan assíncrono (thread separada) para processamento em background.
• Compatível com arquivos grandes: progresso atualizado em tempo real.
• Detecção de modificações: Compara hash atual com anterior para detectar corrupção ou alterações.

Estado Atual

• ✅ TUI moderna implementada com ratatui + crossterm
• ✅ Seleção de diretório funcional com input editável
• ✅ Navegação por teclado completa (↑/k, ↓/j, Enter, Backspace, Ctrl+U, Q/Esc)
• ✅ Validação SHA256 com barra de progresso em tempo real
• ✅ Sistema de cache em disco com TTL e limite de arquivos
• ✅ Scan recursivo em background com persistência automática
• ✅ Estatísticas em tempo real (scanned, cached_ok, errors, cache_hits)
• ✅ Resumo final ao sair com status de cada validação
• ✅ Compila sem erros (cargo check OK)
• ⚠️ Aviso de dead code em ValidationRecord (campos hash e validated_at não lidos no resumo; não afeta execução)

Como Usar

Pré-requisitos

• Rust (versão estável)
• Terminal compatível com ANSI

Execução

# Entrar no diretório do projeto
cd /home/mike/tools_mike/rust-check/kimi

# Compilar e rodar
cargo run

# Ou compilar em modo release para melhor performance
cargo build --release
./target/release/file-hasher

Fluxo de uso

1. Tela inicial: Digite um caminho ou pressione Enter para usar o diretório atual.
2. Navegação: Use ↑/k e ↓/j para mover, Enter para abrir pasta ou validar arquivo, Backspace para voltar.
3. Scan em background: O scanning automático começa imediatamente após selecionar o diretório.
4. Validação: Ao selecionar um arquivo, observe a barra de progresso (usa cache se disponível).
5. Saída: Pressione Q/Esc para sair e ver o resumo das validações realizadas.

Estrutura do Cache

O cache é armazenado em ./cache/ com a seguinte estrutura:

cache/
├── {sha256_do_path1}.json
├── {sha256_do_path2}.json
└── ...

Cada arquivo JSON contém:

{
  "path": "/caminho/completo/do/arquivo",
  "size": 1024,
  "modified_unix": 1735219200,
  "hash": "abc123...",
  "error": null,
  "last_access_unix": 1735305600
}

Estrutura do Projeto

kimi/
├── Cargo.toml          # Dependências (ratatui, crossterm, sha2, etc.)
├── Cargo.lock          # Lockfile
├── CLAUDE.md           # Documentação de arquitetura para desenvolvimento
├── README.md           # Este arquivo
├── cache/              # Diretório de cache (criado em runtime)
├── src/
│   └── main.rs         # Aplicação completa (~1070 linhas)
└── target/             # Artefatos de build

Dependências Principais

• ratatui (v0.26): TUI moderna para renderização de interface
• crossterm (v0.27): Controle de terminal cross-platform
• sha2 (v0.10): Implementação de SHA256
• hex (v0.4): Encoding hexadecimal
• serde (v1.0) + serde_json (v1.0): Serialização do cache
• clap (v4): Parse de argumentos CLI (disponível mas não utilizado atualmente)

Arquitetura

Estados da Aplicação

A aplicação possui três estados principais:

1. SelectDir: Seleção inicial do diretório de trabalho
2. Browse: Navegação pelos arquivos do diretório atual
3. Validating: Validação ativa de um arquivo com barra de progresso

Concorrência

• Scan thread: Varre recursivamente o diretório de trabalho, computando hashes para todos os arquivos
• Validation thread: Valida um arquivo específico com atualizações de progresso
• Main thread: Renderiza UI e processa input do usuário

Cache Strategy

• In-memory cache: BTreeMap<PathBuf, CachedFile> para lookup rápido
• Disk cache: JSON files em ./cache/ para persistência entre sessões
• Cache key: SHA256 do caminho completo do arquivo
• Validation: Size + mtime devem coincidir para reutilizar cache

Observações Técnicas

• Código monolítico: Toda aplicação em src/main.rs (design intencional para utilitário focado)
• Sem suporte a Git: Este diretório não é um repositório git.
• Binário leve: Sem dependências desnecessárias; foco em performance.
• Compatibilidade: Testado em Linux; deve funcionar em outros Unix-like com terminal ANSI.
• Gerenciamento de cache: Limpeza automática a cada 250 arquivos escaneados.

Detalhes de Implementação

Constantes Importantes

• BUFFER_SIZE: 64KB (65536 bytes) para leitura de arquivos
• CACHE_TTL_SECS: 7 dias (604800 segundos)
• CACHE_MAX_FILES: 2000 entradas máximo

Status de Validação

Ao sair, o resumo mostra:

• FINE: Arquivo válido (hash coincide com anterior ou primeira validação)
• TRASH: Hash inválido (diferente do cache anterior - possível corrupção ou modificação)
• ERROR: Erro na leitura do arquivo (permissão, I/O, etc.)

Possíveis Melhorias

• Validação em lote (múltiplos arquivos)
• Exportar relatório JSON/CSV
• Filtros por extensão/tamanho
• Busca/navegação por nome
• Configuração via CLI (TTL, tamanho de cache, etc.)
• Comparação com hash arquivo externo (.sha256sum, etc.)

Licença

Sem licença explícita no momento.