Como garantir que um formatador seja estável e seguro para um projeto inteiro?
Uma ferramenta que muda o arquivo a cada execução, perde comentários ou produz diffs intermináveis não pode entrar no editor nem na CI. Como transformar layout em confiança?
se(condição){
mostre(valor)//nota
}se (condição) {
··mostre(valor) // nota
}VOCABULÁRIO VISUAL
As decisões que tornam o resultado confiável.
determinismo: F(x) = sempre y idempotência: F(F(x)) = F(x) equivalência: parse_semântico(x) = parse_semântico(F(x))
Executar alguns programas antes e depois é verificação complementar: pode encontrar falhas, mas não prova equivalência para todas as entradas.
let once = format(input, config)?;
let twice = format(&once, config)?;
assert_eq!(once, twice);
assert_eq!(semantic_ast(input), semantic_ast(&once));
assert_eq!(comments(input), comments(&once));Um gerador cria árvores Pulso válidas, imprime variações deliberadamente feias e verifica as propriedades. Ele gera estrutura, não bytes aleatórios impossíveis de analisar.
# traco.toml
max_width = 88
indent_width = 2
line_ending = "preserve"
final_newline = trueA busca sobe do arquivo até a raiz do workspace e para ali. Valores fora dos limites são erro; não existem combinações contraditórias. A opinião do Traço mantém diffs previsíveis.
Antes de trabalhar, o Traço lista os .pulso considerados. Respeita .tracoignore, tamanho máximo e a raiz canônica; não segue symlink para fora. Arquivos inalterados não são regravados.
ler + guardar hash/permissões → formatar e validar → conferir que versão não mudou → temporário no mesmo filesystem + sync → preservar permissões + rename → limpar temporário em qualquer falha
seleção do usuário: parte de “a + b” CST encontra ancestral seguro: declaração inteira Traço formata declaração retorna TextEdit somente para o intervalo expandido
traco: off e traco: on preservam uma região literal, mas são validados em pares e não podem atravessar estrutura de modo inseguro.
| Uso | Comportamento |
|---|---|
| --check | exit 1 e diff, sem escrever |
| --write | escrita segura de arquivos |
| stdin/stdout | pipeline sem arquivo |
| LSP | TextEdits para formatting/rangeFormatting |
A Oficina envia versão do documento e só aplica a resposta se ela ainda for atual. Formatar ao salvar não mistura correções do Crivo.
# desenvolvedor escolhe instalar
traco check src/
# pipeline
traco check --config traco.toml .
# exit 0: tudo canônico
# exit 1: mostra arquivos e diffO Traço documenta o hook, mas não o instala sozinho. Também não executa código do projeto durante formatação.
fonte → tokens + trivia → CST + comentários → regras estruturais → documento de layout → Group + fits → texto final → AST equivalente + idempotência → diff → versão conferida → escrita segura → Oficina / CLI / CI recebem o mesmo resultado
rustfmt, Prettier, gofmt e clang-format possuem gramáticas, políticas e escala diferentes. O Traço não cobre todas as construções, plugins ou compatibilidade industrial; ele torna o mecanismo completo observável.
Formatar é preservar estrutura e comentários, construir alternativas, escolher sob restrições e provar que o resultado é semanticamente equivalente e estável.
PROJETO COMPLETO · ESTADO EXATO DESTE CAPÍTULO
Baixe o Traço 1.0.
Pacote exclusivo com código Rust, corpus Pulso, testes e limites documentados. O modo check nunca modifica arquivos.