Escreva regras de análise estática com correções automáticas que não mudam como o código roda

## Mire os padrões comuns e deixe de fora os casos raros Mantenha cada regra conceitualmente simples. Concentre-se em padrões recorrentes e de alto valor e deixe sem suporte os casos extremos raros quando cobri-los tornar a regra menos clara ou as correções mais arriscadas. Defina um contrato de regra estável com uma função de criação e metadados. Em um adaptador baseado em eventos, registre ouvintes de entrada e saída pelos ganchos fornecidos, em vez de retornar um mapa de visitantes convencional. Os ouvintes devem retornar ou produzir com yield objetos de problema; deixe o adaptador realizar os relatórios. Cada problema deve identificar o nó e a mensagem relevantes e acrescentar dados, uma correção ou sugestões somente quando necessário. Se a API do corretor oferecer um mecanismo de cancelamento, use-o sempre que não for possível comprovar que uma edição é segura. Coloque os valores padrão das opções nos metadados para que o framework possa combiná-los de forma consistente, em vez de duplicar a lógica de combinação na regra. ## Decida em qual predefinição a regra entra e comece os nomes das opções com check Trate a posição nas predefinições como uma decisão de produto: - Coloque regras sem controvérsia na predefinição mais segura e em todas as predefinições mais amplas. - Coloque padrões úteis, mas opinativos, somente na predefinição recomendada e em coleções mais amplas. - Mantenha comportamentos de nicho ou que exigem ativação explícita fora das predefinições padrão. Não confunda “sem posicionamento” com “opinativo demais”. Em caso de dúvida, informe o nível proposto e peça à pessoa responsável pela manutenção que decida. Dê nomes positivos no formato `check*` às opções booleanas públicas, para que `true` sempre ative o comportamento. Listas de padrões ignorados ainda podem usar nomes convencionais como `ignore`. Declare explicitamente todos os idiomas compatíveis. Se a lógica depender apenas de nomes de arquivos, texto bruto, comentários ou diretivas, ofereça suporte a vários idiomas quando for viável e use funções auxiliares de raiz e de comentários que abstraiam os tipos de nó específicos de cada idioma. ## Nomeie os helpers pelo que retornam e reutilize os utilitários existentes Nomeie funções auxiliares privadas de acordo com seu contrato observável. `is*`, `has*`, `should*`, `can*` e `needs*` devem retornar valores booleanos, de preferência um `false` explícito em vez de um valor undefined acidental. Use `get*Problem` para um problema opcional e `get*Problems` para vários problemas. Reserve `report*` para funções auxiliares que geram relatórios diretamente. Não combine a geração de relatórios ou o uso de yield com o resultado de um predicado. Construa o problema separadamente e tome a decisão booleana no ponto de chamada. Antes de adicionar uma função auxiliar, inspecione os módulos de AST, utilitários gerais, corretores e regras compartilhadas do repositório e depois verifique utilitários confiáveis do ecossistema. Reutilize exportações agregadas e funções auxiliares estabelecidas para avaliação estática, busca de variáveis, detecção de efeitos colaterais, testes de tokens, resolução de referências, parênteses, pontos e vírgulas e construção de correções. Promova uma função auxiliar somente quando ela for claramente reutilizável; mantenha local a lógica pequena e específica de uma regra. ## Use análise de fluxo de controle só para saber se o código sempre sai Use a análise de fluxo de controle do framework quando uma regra precisar determinar se um ramo ou uma função sempre termina por estruturas como return, throw, break, continue, uma seleção exaustiva ou um loop infinito. Percorrer a AST manualmente costuma ser menos preciso ao lidar com tratamento de exceções, rótulos, aninhamento e segmentos inacessíveis. Para analisar ramos, registre o rastreador de saída de ramos do repositório e consulte-o depois que a condicional externa terminar. Para analisar funções, mantenha um conjunto de segmentos por caminho de código para impedir que funções aninhadas contaminem suas funções pai. Registre a acessibilidade na saída do nó AST relevante; não espere até o fim do caminho de código se o framework já tiver limpado os segmentos atuais. Use verificações de sintaxe mais simples quando a questão for apenas se a última instrução tem um tipo específico, onde os return aparecem ou se um corretor local termina em return ou throw. Não introduza mecanismos de fluxo de controle sem uma necessidade real de verificar acessibilidade. ## Regenere os índices e cabeçalhos de documentação gerados em vez de editá-los à mão Identifique arquivos e regiões gerados antes de editar. Nunca edite manualmente índices, tabelas nem cabeçalhos de documentação gerados. Execute o gerador responsável depois de adicionar, retirar ou renomear regras de origem. Durante a resolução de conflitos, preserve as entradas que constituem a fonte oficial e gere novamente os resultados determinísticos, em vez de reconstruí-los manualmente. Mantenha a documentação escrita por pessoas abaixo de qualquer limite de cabeçalho gerado. Use nos exemplos a sintaxe de configuração preferida pelo repositório; não mude para exemplos semelhantes a JSON com aspas, a menos que o exemplo seja explicitamente JSON. Quando também houver padrões de regras compartilhados em um repositório ou pacote relacionado, considere se a mesma alteração deve ser transferida. Trate isso como uma decisão explícita de compatibilidade, não como uma edição automática entre projetos. ## Rode só os testes da regra durante o desenvolvimento e a suíte completa no final Escreva testes focados antes ou durante a implementação. Prefira testes de instantâneo quando a infraestrutura de testes puder capturar em conjunto diagnósticos, correções e sugestões, e use modos de analisador especializados somente nos casos que precisarem deles. Durante o desenvolvimento, execute apenas o teste da regra em questão. Atualize instantâneos intencionalmente e retire marcadores temporários de testes focados antes de concluir. Não execute testes de integração lentos como parte do ciclo normal de edição. Teste a nova regra no próprio projeto depois de implementá-la e novamente após cada correção de lógica, pois as correções frequentemente revelam violações em outros pontos. No final, execute o linter real do repositório, os testes focados e o teste no próprio projeto; depois, execute uma única vez a suíte completa de testes. Não substitua o linter por outra ferramenta de lint apenas porque ela relata resultados limpos. ## Teste as correções com comentários e sintaxe delicada Teste comportamento, ausências de correspondência, correções e sugestões sem duplicar a cobertura. Inclua casos relevantes destas famílias: - sintaxe tipada, asserções de tipo, genéricos e encadeamento opcional; - JSX, comentários, parênteses extras e expressões aninhadas e encadeadas; - propriedades calculadas, modelos, propagação e desestruturação; - valores de retorno usados em comparação com não usados; - análise apenas de sintaxe em comparação com informações completas de tipo quando a regra depende de tipos. Teste os casos que uma regra ignora intencionalmente para que o limite fique documentado. Verifique correções na presença de comentários e de riscos de inserção automática de ponto e vírgula. Se um caso precisar de um analisador diferente, configure-o no menor escopo de teste capaz de expressar o requisito. ## Ofereça correção automática só quando ela não muda como o código roda e preserve os comentários Forneça uma correção automática somente quando ela não puder alterar o comportamento em tempo de execução. Quando o comportamento puder mudar, prefira uma sugestão. Considere obrigatória a preservação de comentários: se uma substituição ou retirada contiver comentários, cancele a correção ou use uma edição sensível ao intervalo que os mantenha no lugar. Antes de emitir uma correção, verifique se a substituição precisa de parênteses, se um colchete ou parêntese inicial exige ponto e vírgula e se tokens adjacentes precisam de espaçamento. Use correções de gerador em operações com várias edições. Preserve o comportamento do encadeamento opcional e evite edições inseguras quando um valor for consumido de forma diferente de uma expressão independente. Não torne as correções desproporcionalmente complexas apenas para preservar elementos embutidos ocultados por nomes locais, efeitos colaterais de acessores ou proxies, ou lacunas em arrays esparsos, a menos que o repositório já tenha uma proteção local simples. Informe o problema sem correção quando não for possível estabelecer a segurança. ## Nomeie a regra, crie-a pela estrutura inicial e leve-a dos testes ao commit Escolha nomes que descrevam a estrutura e a intenção: use prefixos como `no-`, `prefer-`, `require-` ou `consistent-` quando eles esclarecerem o comportamento. Nomeie o alvo, não a substituição proposta, e evite nomes vagos. Use a estrutura inicial do repositório para criar a implementação, o teste, a documentação e as entradas de índice geradas. Depois, siga esta sequência: 1. Adicione testes que falhem ou sejam representativos. 2. Implemente a menor lógica de regra que os satisfaça. 3. Documente o comportamento e as exclusões intencionais. 4. Execute os testes focados e o comando de lint oficial. 5. Teste no próprio projeto e, no final, execute a suíte completa. 6. Confirme que os arquivos gerados estejam atualizados e que os arquivos temporários tenham sido retirados. Use a convenção de mensagens de commit do projeto, incluindo a pontuação obrigatória em torno dos nomes de regras e opções. A entrega estará concluída somente quando o código-fonte, os testes, a documentação, as áreas geradas e os resultados de validação estiverem de acordo.