Altere um workspace Rust de bibliotecas e CLI e compare com a ferramenta de referência

## Coloque as mudanças no crate responsável e mantenha leves as APIs de baixo nível Trate o repositório como um workspace com vários crates que atende tanto usuários de bibliotecas quanto da linha de comando. Leia os manifestos do workspace antes de editar para conhecer a versão mínima compatível do Rust, o grafo de funcionalidades, as responsabilidades dos crates e os pontos de entrada públicos. Separe o plumbing de baixo nível do porcelain de alto nível: - APIs de plumbing devem priorizar referências, expor explicitamente o estado de trabalho mutável e evitar clones por conveniência; - APIs de porcelain podem trocar alguma alocação ou propriedade por facilidade de uso; - objetos leves de plataforma normalmente devem tomar o repositório por empréstimo; - caches dispendiosos podem possuir ou clonar o estado do repositório quando, de outro modo, os tempos de vida dominariam a API. Use `Options` para comportamentos ramificados que possam ter valores padrão. Use `Context` para dados necessários à execução da operação e que, portanto, não podem receber um padrão com segurança. Coloque as alterações no crate que detém a estrutura de dados ou a operação relevante. Mantenha o comportamento compartilhado de linha de comando em uma camada CLI comum, em vez de duplicá-lo entre binários. Antes de alterar uma superfície pública, considere tanto os consumidores diretos da biblioteca quanto o comportamento da linha de comando. ## Comece com um teste que falha e compare com a ferramenta de referência Comece as mudanças de comportamento com um teste de regressão que falhe pelo motivo pretendido. Mantenha o teste focado no comportamento observável; deixe que o compilador Rust detecte erros rotineiros de tipos e propriedade. Ao implementar um protocolo ou formato de arquivo estabelecido, use a implementação de referência dominante como oráculo sempre que viável. Execute casos equivalentes nas duas implementações e investigue qualquer diferença semântica, em vez de presumir compatibilidade. Execute os testes existentes antes de editar para que falhas preexistentes não sejam atribuídas à alteração. Use: - testes unitários para algoritmos locais e transformações de dados; - testes de integração para limites entre crates; - testes de jornada para o comportamento de linha de comando de ponta a ponta; - repositórios reais ou conjuntos de dados realistas para caminhos sensíveis à compatibilidade. Toda mensagem de asserção deve explicar o invariante verificado, e não apenas informar que uma asserção falhou. Adicione documentação clara dos fixtures que descreva o comportamento em teste e quais detalhes são essenciais. Prefira strings de documentação quando o sistema de fixtures oferecer suporte a elas. ## Troque unwrap() por erros que digam o que falhou e onde Nunca use `unwrap()` em código de produção. Evite-o também nos testes; prefira `?` ou use `expect()` apenas com uma explicação concisa de por que a condição precisa ser verdadeira. Preserve cadeias de erros completas para que os usuários entendam o que falhou e onde. Binários de linha de comando podem usar um tipo de erro flexível no nível superior, mas crates de nível inferior devem seguir a convenção estruturada de erros do workspace. Antes de adicionar um erro, examine o manifesto do crate e o código próximo: - se o crate já usa o framework de erros mais recente que carrega contexto, continue esse padrão; - se ainda usa um enum de erros legado baseado em derive, mantenha a consistência dentro desse crate, a menos que a migração esteja explicitamente no escopo. No padrão que carrega contexto: - crie mensagens estáticas ou formatadas por meio do auxiliar do projeto; - adicione contexto ao propagar um erro da função chamada; - gere uma mensagem independente quando não houver erro da função chamada; - apague os tipos dos erros somente quando um limite de callback exigir; - converta um wrapper de exceção do projeto em um erro padrão apenas nos limites de interoperabilidade. Se o wrapper de exceção do projeto deliberadamente não implementar o trait de erro padrão, não o force em APIs genéricas de erro. Converta-o com o método de limite fornecido. Testes que retornam erros padrão encaixotados devem mapear o wrapper antes de usar `?`. Use os traits de extensão de erros e as importações já estabelecidos, em vez de reconstruir manualmente as cadeias de erros. ## Evite clones extras e trate os caminhos do repositório como bytes Prefira referências em crates de baixo nível para evitar clones dispendiosos. Não desanexe um handle respaldado pelo repositório, a menos que um valor com propriedade seja explicitamente necessário e a API não possa aceitar a forma anexada. Use a abstração de concorrência do workspace para mutabilidade interna. Não a substitua por primitivas de sincronização sem relação sem antes verificar a compatibilidade das funcionalidades e o comportamento da plataforma. Trate os caminhos do controle de versão como dados orientados a bytes, inclusive em plataformas cujas APIs nativas de caminhos usam codificações diferentes. Converta caminhos do repositório em caminhos do sistema operacional somente por meio dos utilitários de caminho do projeto ou de um tipo de limite dedicado. Não presuma que um caminho válido do repositório seja Unicode válido. Evite conversões com perda em código de análise, comparação, armazenamento e protocolo. Meça os caminhos críticos antes de adicionar propriedade, cache ou alocação. A conveniência pertence à camada de alto nível; as primitivas de baixo nível devem preservar o controle e um custo previsível. ## Teste todas as combinações de funcionalidades, não só o build padrão Use o executor de tarefas do repositório para o comando abrangente de testes, as verificações de configuração do workspace, o lint, os testes de jornada e as compilações da documentação. Use `cargo test` diretamente apenas quando uma execução limitada a testes unitários for intencionalmente suficiente. Verifique as variantes de release compatíveis, incluindo a compilação padrão e quaisquer conjuntos enxutos ou mínimos de dependências. Uma alteração estará incompleta se funcionar somente com as funcionalidades padrão. Exercite as combinações de funcionalidades documentadas do workspace, incluindo variantes pequenas, enxutas, máximas e puras, quando existirem. Verifique se as dependências opcionais e as abstrações de plataforma compilam em cada combinação afetada. Em plataformas onde o conteúdo dos fixtures gerados varia, use o mecanismo de estabilização de arquivos compactados do repositório. Prefira arquivos compactados de fixtures já empacotados à geração local da plataforma quando a estabilidade byte a byte for importante. Se o repositório definir um flag de ambiente específico da plataforma para testes de arquivos compactados no macOS ou Windows, aplique-o exatamente como documentado. Não ignore silenciosamente os testes afetados em outras plataformas. Execute testes de comando de ponta a ponta para alterações da CLI visíveis ao usuário e compare com a implementação de referência quando for prático. ## Escreva commits úteis para o changelog e marque mudanças incompatíveis Use commits convencionais com propósito: - adicione um prefixo convencional somente quando a alteração pertencer ao changelog; - use `feat:` e `fix:` para funcionalidades e correções visíveis ao usuário; - omita o prefixo em refatorações internas e tarefas de manutenção; - marque toda alteração incompatível com um sufixo `!`. Escreva assuntos de commit que indiquem o propósito visível ao usuário e incluam a referência da issue ou da revisão quando o projeto exigir. Quando uma alteração incompatível afetar vários crates, divida-a por crate se uma só mensagem de commit não puder descrever com precisão todos os impactos. Coloque a alteração incompatível da API no primeiro commit e as adaptações dos componentes dependentes em um commit seguinte. Trate as mensagens de commit como entradas do release quando a automação de release derivar delas o versionamento ou os changelogs. Atualize guias de alto nível, instruções de contribuição, notas de desenvolvimento, registros de status dos crates e documentação de estabilidade sempre que a alteração de código os afetar diretamente. Use como referência de compatibilidade a versão da ferramenta de referência disponível no ambiente principal de CI, a menos que o projeto defina um alvo mais rigoroso. ## Passe pela lista final, da camada do crate às mensagens de commit Antes da conclusão: 1. identifique se a alteração pertence ao plumbing ou ao porcelain; 2. examine os padrões estabelecidos em crates semelhantes; 3. confirme que o tratamento de erros corresponde ao framework atual desse crate; 4. verifique se nenhum `unwrap()` foi introduzido no código de produção; 5. verifique todas as combinações de funcionalidades e variantes de release afetadas; 6. considere separadamente os consumidores da biblioteca e os usuários da linha de comando; 7. execute testes focados, do workspace, de jornada e de compatibilidade, conforme aplicável; 8. confirme que os caminhos orientados a bytes continuam sem perdas entre plataformas; 9. revise novos clones, desanexações, caches e sincronizações quanto à necessidade mensurável; 10. atualize a documentação diretamente relacionada; 11. confirme que as mensagens de commit descrevem corretamente o impacto no changelog e nas alterações incompatíveis. Informe qualquer conjunto de funcionalidades, plataforma, comparação com a referência ou variante de release não testada, junto com o pré-requisito exato ausente. Não alegue compatibilidade em todo o workspace com base em uma execução de testes unitários usando apenas as funcionalidades padrão.