vibator/vibator

Configurando o vibator

Referência: npx vibator docs configuration imprime o formato de configuração e npx vibator docs rules imprime cada regra com suas opções e padrões. Esta skill é o fluxo de trabalho; esses documentos são o contrato.

A configuração é uma tarefa de descoberta: a configuração correta é determinada pelo que o projeto realmente contém. Inspecione primeiro, escreva segundo, execute terceiro.

Regras básicas

• Nunca enfraqueça um portão para fazê-lo passar. Desligar uma regra, aumentar seu orçamento ou excluir um arquivo porque ele falha atualmente esconde o problema em vez de corrigi-lo. Corrija a constatação, ou deixe a regra falhando e diga isso. A única saída por linha é // vibator-ignore: <motivo>, e o motivo é obrigatório.
• Configure apenas o que difere dos padrões. Cada regra já é executada com sua severidade padrão e sem nenhuma configuração. Uma configuração que repete todos os padrões enterra as linhas que importam.
• include e exclude substituem os padrões de uma regra. Eles não se mesclam. Copie os padrões que você ainda deseja antes de restringir.
• Nunca defina recommended: false para fazer uma execução passar. Isso desabilita todas as regras que a configuração não nomeia, incluindo as que passam. Ele existe para declarar uma seleção deliberada, e essa seleção é uma decisão humana.
• Uma configuração que o projeto estende não é sua para editar. Uma predefinição estabelece um padrão que vários projetos compartilham. Configure a diferença localmente, ou peça a um humano para alterar a predefinição. Nunca silencie uma constatação editando um arquivo em node_modules; a próxima instalação o substituirá de qualquer maneira.

Passos

1. Comece de um arquivo válido. Se nenhum vibator.json existir, execute npx vibator init; ele escreve a linha $schema que dá aos editores validação. Em seguida, npx vibator list mostra cada regra e seu padrão. Antes de escrever suas próprias regras, verifique se o projeto já estende uma predefinição, ou se existe uma para estender (um pacote estilo @scope/quality em package.json, ou a mesma configuração repetida em repositórios irmãos). Estendê-la é melhor do que repeti-la; veja "Construindo sobre uma predefinição compartilhada" abaixo.

2. Execute uma vez, sem configuração: npx vibator --reporter json. Isso mostra quais regras passam, quais falham e quais quebraram por falta de opções. Leia contagens antes de diagnósticos; uma regra com 400 constatações precisa de uma decisão, não 400 correções hoje (veja o passo 6).

3. Descubra o que as regras desligadas por padrão precisam. Cada uma está desligada porque não pode agir sem conhecimento do projeto. Procure por ela:

   • locale-parity: encontre o diretório de localidades (locales/, i18n/, public/locales/). Anote o layout: um diretório por localidade (layout: "directory-per-locale") ou um arquivo por localidade ("file-per-locale"), e qual localidade é a fonte.
   • codegen-drift: leia os scripts de package.json para geradores (db:generate, openapi, graphql-codegen) e encontre os caminhos que cada um escreve. Configure uma entrada por gerador com name, command, paths.
   • banned-patterns: leia as convenções de revisão do projeto (CONTRIBUTING, documentos de estilo, comentários recorrentes de revisão). Cada "nunca faça X" em formato de padrão se torna uma entrada com seu próprio message, expected e fix, escrita com tanto cuidado quanto a de uma regra embutida.
   • no-deprecated-apis: liste os tsconfigs; um monorepo deseja cada projeto que deve ser verificado em options.projects.

4. Vincule documentos existentes do projeto às regras com guidelines. Se o repositório tiver um AGENTS.md, CLAUDE.md ou documento de estilo que estabeleça um padrão que uma regra impõe, mapeie-o: "guidelines": {"AGENTS.md": ["tsdoc-coverage"]}. Use o campo docs por regra somente quando o padrão do projeto substituir a diretriz enviada em vez de adicionar contexto.

5. Use a forma de array para padrões divididos. Uma regra pode ser executada várias vezes com diferentes globs e opções:

   "max-file-size": [
     {"include": ["src/**"], "options": {"maxKb": 256}},
     {"include": ["assets/**"], "options": {"maxKb": 4096}}
   ]
   

6. Adote incrementalmente em uma base de código legada com --changed, não enfraquecendo. Verifique o trabalho novo imediatamente (npx vibator --changed, ou --since origin/main no CI para o diff inteiro do pull request) enquanto o backlog diminui. Para regras com muitas constatações, use warn no meio tempo: as constatações permanecem visíveis sem bloquear. Não use off para significar "depois".

7. Verifique o resultado. Execute npx vibator e confirme: toda regra habilitada é executada (uma regra que quebrou é um bug de configuração e sua mensagem diz o que estava faltando), as constatações restantes são reais, e npx vibator explain <rule> mostra a diretriz correta para qualquer coisa que você substituiu.

Construindo sobre uma predefinição compartilhada

extends recebe um caminho começando com . ou um especificador de pacote, resolvido em relação ao arquivo que o declara. Entradas posteriores vencem as anteriores, e as configurações do próprio arquivo vencem todas elas.

{
  "extends": ["@acme/quality/vibator.json"],
  "rules": { "max-file-size": "warn" }
}

A mesclagem segue o Biome, então se comporta como os usuários dessa pilha esperam. Duas consequências para acertar:

• Uma severidade nua mantém todo o resto. Escrever "max-file-size": "warn" sobre uma predefinição que definiu maxKb e include muda apenas a severidade; o orçamento e os globs são herdados. Você não precisa repeti-los, e repeti-los é como um projeto se desvia silenciosamente de sua predefinição.
• Arrays substituem, eles não concatenam. Para adicionar uma entrada a uma lista allow ou patterns herdada, escreva a lista inteira que você deseja. Isso é deliberado: torna possível remover uma entrada herdada.

Escreva apenas a diferença. Uma configuração que repete o que a predefinição já diz é indistinguível de uma que discorda dela, e a próxima atualização da predefinição não alcançará os campos que você copiou.

Uma predefinição construída como uma seleção curada define "recommended": false e lista as regras que deseja. Sob tal predefinição, regras não nomeadas não são executadas, então verifique-a antes de concluir que uma regra está faltando.

Caminhos de diretrizes são resolvidos da mesma forma: entradas docs e guidelines declaradas por uma predefinição são resolvidas em relação à predefinição, então as constatações apontam para os documentos que a acompanham. Seus próprios caminhos ainda são resolvidos em relação à raiz do projeto.

Política de severidade

• error: regras determinísticas com quase zero falsos positivos.
• warn: regras que podem estar erradas sobre uma base de código que não viram (env-example-sync corresponde a texto; prefer-array-methods não pode distinguir um array de um Set), e adoção provisória de regras com um grande backlog.
• off: apenas para regras que não se aplicam (sem localidades significa sem locale-parity), nunca como uma forma de passar.

Erros comuns

• Escrever include e perder as exclusões padrão da regra (testes, .d.ts).
• Repetir as opções de uma predefinição ao lado de uma substituição de severidade, assumindo que uma severidade nua as descarta. Não descarta, e a cópia para de rastrear a predefinição.
• Habilitar codegen-drift com um gerador que precisa de serviços ou segredos que o ambiente não possui. A regra executa o comando de verdade.
• Mapear cada documento em cada regra em guidelines. Mapeie apenas documentos que realmente estabelecem o padrão daquela regra.
• Editar a configuração para encerrar uma execução com falha em vez de corrigir as constatações. Se um humano pediu o portão, apenas um humano decide rebaixá-lo.