Skip to content

LEIAME.md

Latest commit

 

History

History
334 lines (237 loc) · 7.65 KB

LEIAME.md

File metadata and controls

334 lines (237 loc) · 7.65 KB

RSFE - Rust Source File Encoding Fixer

Read in English | Leia em Português

Ferramenta de linha de comando em Rust para validação e correção automática de encoding de arquivos em projetos, projetada para ser executada como pre-commit hook via Husky.

Características

  • Detecção automática de encoding: Detecta automaticamente o encoding de arquivos usando chardetng
  • Conversão inteligente: Converte apenas quando necessário para evitar alterações desnecessárias
  • Configuração flexível: Suporta arquivo de configuração com padrões glob
  • Performance otimizada: Processamento paralelo usando Rayon
  • Integração com Git: Processa apenas arquivos staged ou todo o projeto
  • Interface interativa: Permite seleção de encoding quando não há configuração
  • Respeita .gitignore: Ignora automaticamente arquivos listados no .gitignore

Instalação

Pré-requisitos

  • Rust 1.70+ (instale via rustup)
  • Git (para integração com pre-commit)
  • Node.js e npm (opcional, para integração com Husky)

Instalação rápida

# Clone ou copie o projeto
git clone <seu-repositorio>
cd rs-precommit-fix-encode

# Execute o script de instalação
chmod +x install.sh
./install.sh

O script de instalação irá:

  1. Compilar o projeto em modo release
  2. Configurar Husky automaticamente (se detectar projeto Node.js)
  3. Criar o hook de pre-commit

Instalação manual

# Compilar
cargo build --release

# O binário estará em: ./target/release/rsfe

Configuração

Arquivo rsfe.conf

Crie um arquivo rsfe.conf na raiz do seu projeto. Formato:

# Comentários começam com #
<padrão-glob> <ENCODING>

# Exemplo:
** UTF-8                    # Padrão para todos os arquivos
**/*.js UTF-8               # Arquivos JavaScript
**/*.py UTF-8               # Arquivos Python
legacy/** AUTO              # Detecção automática para pasta legacy
old-data/**/*.txt WINDOWS-1252  # Encoding específico

Encodings suportados

  • UTF-8 (padrão recomendado)
  • UTF-16LE (UTF-16 Little Endian)
  • UTF-16BE (UTF-16 Big Endian)
  • ISO-8859-1 (Latin-1)
  • WINDOWS-1252 (CP1252)
  • AUTO (detecção automática)
  • Qualquer encoding suportado pela biblioteca encoding_rs

Exemplo de configuração

Copie o arquivo de exemplo:

cp rsfe.conf.example rsfe.conf

Edite conforme necessário para seu projeto.

Uso

Modo standalone

# Processar todo o projeto
./target/release/rsfe

# Se não houver rsfe.conf, será solicitado a escolher o encoding padrão

Com Git (arquivos staged)

# Adiciona arquivos ao stage
git add .

# Executa o rsfe (processará apenas arquivos staged)
./target/release/rsfe

Como pre-commit hook com Husky

Se você instalou via install.sh, o hook já está configurado. Cada commit irá:

  1. Executar rsfe nos arquivos staged
  2. Converter encodings se necessário
  3. Re-adicionar arquivos modificados ao stage
  4. Prosseguir com o commit
# Uso normal do git
git add .
git commit -m "Minha mensagem"
# rsfe será executado automaticamente

Configuração manual do Git hook

Se não usar Husky, adicione ao .git/hooks/pre-commit:

#!/bin/sh

# Executa o rsfe
./target/release/rsfe

# Se falhar, cancela o commit
if [ $? -ne 0 ]; then
    echo "❌ rsfe falhou. Corrija os erros antes de commitar."
    exit 1
fi

# Re-adiciona os arquivos modificados
git add -u

exit 0

Torne o hook executável:

chmod +x .git/hooks/pre-commit

Como funciona

Fluxo de execução

  1. Carrega configuração: Lê rsfe.conf ou solicita encoding padrão
  2. Coleta arquivos:
    • Se em repositório git com arquivos staged: processa apenas staged
    • Caso contrário: processa todo o projeto
  3. Filtra arquivos: Ignora binários e respeita .gitignore
  4. Processa em paralelo: Usa Rayon para processamento multi-thread
  5. Para cada arquivo:
    • Determina encoding alvo baseado nas regras
    • Detecta encoding atual
    • Verifica se conversão é necessária
    • Converte se necessário
  6. Reporta resultados: Mostra quantos arquivos foram convertidos

Detecção de conversão necessária

O RSFE só converte quando realmente necessário, verificando:

  1. Se há erros ao decodificar com o encoding alvo
  2. Se ao recodificar o conteúdo é diferente do original

Isso evita commits desnecessários de arquivos que já estão no encoding correto.

Performance

O RSFE é otimizado para performance:

  • Processamento paralelo: Usa todos os cores da CPU via Rayon
  • Leitura inteligente: Ignora automaticamente arquivos binários
  • Cache de detecção: chardetng é eficiente para detecção de encoding
  • Conversão condicional: Só converte quando realmente necessário

Benchmark típico (depende do hardware):

  • ~10.000 arquivos processados em ~2-5 segundos
  • Conversões necessárias: adiciona ~1-2ms por arquivo

Arquivos ignorados

Por padrão, o RSFE ignora:

Diretórios

  • node_modules
  • target
  • dist
  • build
  • .git
  • .idea
  • .vscode
  • Qualquer diretório no .gitignore

Extensões (binários)

  • Imagens: .png, .jpg, .jpeg, .gif
  • Documentos: .pdf
  • Arquivos compactados: .zip, .tar, .gz
  • Executáveis: .exe, .dll, .so, .dylib

Exemplos de uso

Projeto JavaScript/TypeScript

# rsfe.conf
** UTF-8
**/*.js UTF-8
**/*.ts UTF-8
**/*.jsx UTF-8
**/*.tsx UTF-8
**/*.json UTF-8

Projeto Python

# rsfe.conf
** UTF-8
**/*.py UTF-8
**/*.md UTF-8
requirements.txt UTF-8

Projeto com arquivos legados

# rsfe.conf
** UTF-8
legacy/** AUTO           # Detecta automaticamente
docs/old/*.txt WINDOWS-1252

Solução de problemas

"Rust não está instalado"

Instale o Rust via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

"Falha na compilação"

Verifique a versão do Rust:

rustc --version  # Deve ser 1.70+

Atualize se necessário:

rustup update

Arquivos binários sendo processados

Adicione a extensão à lista de ignorados em src/main.rs:251.

Encoding não suportado

Consulte a documentação do encoding_rs para encodings suportados.

Desenvolvimento

Estrutura do projeto

rs-precommit-fix-encode/
├── src/
│   └── main.rs          # Código principal
├── Cargo.toml           # Dependências
├── rsfe.conf.example    # Exemplo de configuração
├── install.sh           # Script de instalação
├── .husky/
│   └── pre-commit       # Hook do Husky
├── README.md            # Documentação em inglês
└── LEIAME.md            # Documentação em português

Executar em modo debug

cargo run

Testes

cargo test

Build otimizado

cargo build --release --target x86_64-unknown-linux-musl  # Linux estático

Contribuindo

  1. Fork o projeto
  2. Crie uma branch para sua feature (git checkout -b feature/MinhaFeature)
  3. Commit suas mudanças (git commit -m 'Adiciona MinhaFeature')
  4. Push para a branch (git push origin feature/MinhaFeature)
  5. Abra um Pull Request

Licença

MIT License - veja o arquivo LICENSE para detalhes.

Autor

Criado para garantir consistência de encoding em projetos e evitar problemas de caracteres especiais em commits.

Links úteis