Lucas RayanandClaude Sonnet 5
3755fc7d2a
README reescrito refletindo o estado real pós-1.0.0 (ext4, APFS, HFS+, Btrfs, XFS, BitLocker, LUKS, FileVault 2, RAID, LVM, E01/Ex01, AFF4, JPEG fragmentado, MP4 sem moov), com links para a documentação nova. ROADMAP.md: histórico de versões e dez áreas com estado (feito, parcial, planejado, ideia de longo prazo), incluindo cadeia de custódia, análise forense, interpretação de artefatos e extração de dispositivos móveis. docs/suporte.md, docs/cli.md e docs/arquitetura.md: matriz de suporte, referência de comandos e mapa dos módulos do núcleo. Removido docs/ do .gitignore, já que passa a ser documentação pública do projeto. CONTRIBUTING.md: seções para adicionar sistema de arquivos, baixar dados de referência e manter a documentação atualizada. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
40 lines
2.1 KiB
Markdown
40 lines
2.1 KiB
Markdown
# Contribuindo com o Guará
|
|
|
|
Obrigado por ajudar! Regras de ouro:
|
|
|
|
1. **Nunca escreva na origem.** Qualquer código que abra um dispositivo deve usar `source::open_path` (somente leitura). PRs que escrevem no disco de origem são recusados.
|
|
2. **Teste com dados reais.** Novos detectores/leitores precisam de teste que recupera um arquivo conhecido bit a bit (veja `crates/guara-core/tests/` e `scripts/make-fixtures.sh`).
|
|
3. **Seja honesto sobre confiança.** Se o conteúdo não puder ser validado, a confiança é no máximo média.
|
|
|
|
## Fluxo
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
cargo clippy --workspace --all-targets
|
|
cargo test --workspace
|
|
```
|
|
|
|
No Linux os testes geram imagens com `mtools`, `ntfs-3g`, `e2fsprogs`, `exfatprogs`, `imagemagick`, `zip` e `python3`. Sem essas ferramentas os testes com imagem são ignorados (defina `GUARA_REQUIRE_FIXTURES=1` para falhar).
|
|
|
|
Para as imagens de referência externas (BitLocker, FileVault 2, dfvfs, AFF4), rode `scripts/fetch-testdata.sh`; sem elas esses testes são pulados. O teste de BitLocker leva cerca de 75 s.
|
|
|
|
## Onde mexer
|
|
|
|
Mapa dos módulos em [docs/arquitetura.md](docs/arquitetura.md). O que falta e o que é bem-vindo está no [ROADMAP](ROADMAP.md).
|
|
|
|
## Adicionando um formato de arquivo
|
|
|
|
Detectores simples ficam em `crates/guara-core/src/signatures.rs`; os mais novos, em `formats.rs`. Acrescente o detector em `detect`, o primeiro byte em `might_start`, a extensão em `category_for_ext`/`matches_ext` e um arquivo real ao `scripts/make-fixtures.sh` com teste de bit-exatidão.
|
|
|
|
## Adicionando um sistema de arquivos
|
|
|
|
Crie o leitor em `crates/guara-core/src/fs/`, registre-o em `fs/mod.rs` e traga um teste com imagem real ou de referência. **Não entregamos leitor sem validação**: é por isso que ReFS e Storage Spaces ainda não existem. Imagens pequenas e sem dados pessoais são o melhor presente que se pode dar ao projeto.
|
|
|
|
## Documentação
|
|
|
|
Português, sem travessões. Ao mudar um recurso, atualize [docs/suporte.md](docs/suporte.md), o [CHANGELOG](CHANGELOG.md) e, se for o caso, o [ROADMAP](ROADMAP.md).
|
|
|
|
## Commits
|
|
|
|
Mensagens curtas no imperativo (`corrige leitura de runs esparsos no NTFS`). Uma mudança lógica por PR.
|