Faça alterações pequenas e testadas em um grande monorepositório TypeScript

## Conheça a estrutura e as ferramentas do repositório antes de editar Trate o guia canônico de agentes do repositório como a única fonte de instruções. Mantenha os pontos de entrada alternativos dos agentes como referências breves e atualize o guia canônico quando mudarem a arquitetura, as ferramentas, as versões, os fluxos de trabalho ou as regras para colaboradores. Identifique: - a raiz real do repositório, a área principal do código-fonte, a área dos scripts de compilação, a documentação, os aplicativos de teste e os espaços de trabalho gerados; - o ramo-base exigido, a versão do ambiente de execução, o gerenciador de pacotes, o orquestrador de tarefas, o analisador estático, o formatador e os sistemas operacionais da integração contínua; - as exportações públicas em contraste com as exportações explicitamente internas; - os verificadores de tipos específicos de cada pacote e qualquer divisão de versões do compilador entre as verificações do repositório, as ferramentas do editor e os consumidores posteriores da API. Mantenha a configuração compartilhada válida para todos os caminhos de compilação compatíveis. Não adote uma opção ou sintaxe apenas porque o verificador mais recente a aceita. Em ferramentas modulares de interface, diferencie os renderizadores em tempo de execução, os mecanismos de empacotamento e as integrações com estruturas de desenvolvimento que combinam ambos com a configuração da estrutura. Preserve uma arquitetura de inicialização rápida, como a indexação estática antes do carregamento em tempo de execução; um único módulo inválido do usuário não deve derrubar toda a interface de navegação ou administração. ## Execute só as compilações e verificações de que a alteração precisa Execute os comandos no diretório de trabalho documentado e use os nomes dos projetos do espaço de trabalho, não os nomes dos pacotes publicados, ao se referir ao grafo de tarefas. Comece com tarefas que aproveitem o cache, considerem as dependências e não usem a configuração de produção: 1. compile o projeto ou conjunto de pacotes afetado; 2. execute verificações de tipos delimitadas; 3. formate e analise estaticamente os arquivos alterados; 4. execute os testes relevantes mais próximos; 5. valide o comportamento na interface interna de desenvolvimento. Avance para a configuração de produção, ambientes isolados gerados ou fluxos equivalentes à integração contínua somente quando a mudança depender da integração de modelos, da ligação das tarefas de produção ou do comportamento entre pacotes. Respeite as dependências entre tarefas, a menos que esteja retomando deliberadamente a partir de uma fase posterior já verificada. Não inicie servidores de desenvolvimento de longa duração como ação padrão. Comandos que exigem um modelo, destino ou ambiente devem recebê-lo explicitamente. Quando um ambiente isolado gerado falhar, use a interface interna documentada como alternativa para o diagnóstico antes de alterar a arquitetura de compilação. ## Escolha o tipo de teste conforme o código e evite que os testes interfiram entre si Associe a forma de teste ao comportamento: - teste os componentes renderizados por meio de histórias mantidas junto ao código e funções de interação, incluindo a acessibilidade e o comportamento do usuário; - use testes unitários para utilitários puros, ganchos e módulos que não fazem renderização; - use ferramentas visuais para a aparência; - use conjuntos de testes de ponta a ponta, de fumaça ou de execução para os contratos de integração. Teste o comportamento exportado e os efeitos colaterais observáveis, não os detalhes privados da implementação. Não duplique garantias já impostas por tipos, regras de análise estática, interações das histórias ou testes de navegador de nível superior. Em código de sistema de arquivos, prefira um sistema de arquivos em memória a diretórios temporários reais ou à substituição integral de módulos. Redefina o estado virtual antes de cada teste, redirecione somente os métodos necessários do sistema de arquivos e verifique o estado do disco virtual quando isso for útil. Nunca faça atribuições diretas a valores globais implícitos nos testes. Use os simuladores globais rastreados pela estrutura de testes e restaure-os após cada teste, inclusive as chaves que não existiam antes. A atribuição direta cria vazamentos entre arquivos que dependem da ordem de execução. Normalize os caminhos esperados com os utilitários de caminho do ambiente de execução para que as verificações do sistema de arquivos passem tanto no Unix quanto no Windows. ## Confira primeiro as premissas e não adicione abstrações desnecessárias Verifique as premissas sobre o ambiente com uma pequena sondagem descartável antes de basear a arquitetura nelas. Não transforme uma crença não testada sobre empacotadores, metadados, carregadores ou saída gerada em um comentário ou uma abstração permanente. Registre primeiro as premissas duradouras por meio dos tipos e das regras de análise estática existentes. Se a imposição estática for impraticável, acrescente uma verificação barata em tempo de execução no limite, para que as violações falhem perto de sua origem. Prefira a remoção e a objetividade à flexibilidade especulativa. Não acrescente abstrações, alternativas ou pontos de extensão para consumidores que não existem. Comentários são documentação de manutenção, não transcrições de investigações. Explique o motivo duradouro em uma ou duas frases; omita códigos de chamados, históricos de sondagens, narrativas de comparação de bytes e referências frágeis a números de linha. Use ampla cobertura de casos extremos em caminhos sensíveis à segurança e migrações de sistemas legados. Restrinja o código de compatibilidade a uma janela de versões explícita, para que ele possa ser removido quando o suporte terminar. ## Não mexa nos arquivos gerados sem motivo e use as ferramentas de formatação e registros do repositório Execute o formatador do repositório após editar; em seguida, analise estaticamente os arquivos alterados e execute os testes relevantes. Use as ferramentas configuradas; não substitua analisadores desativados nem formate manualmente o código cuja formatação pertence ao formatador. Execute novos scripts TypeScript pelo caminho nativo atual do repositório e use extensões de importação TypeScript explícitas onde estiver configurado. Migre carregadores antigos somente dentro do escopo alterado. Use a abstração de registros do projeto no código normal do servidor e do cliente. Reserve chamadas diretas ao console para scripts isolados nos quais importar o registrador não seja razoável. Nunca confirme no controle de versão alterações acidentais em arquivos gerados. Um artefato gerado só pode mudar quando for uma consequência determinística de uma alteração intencional no código-fonte do mesmo trabalho. Caso contrário, deixe-o intacto e relate desvios recorrentes do gerador. Considere Unix e Windows em caminhos, subprocessos e testes. Trate a cobertura de plataformas da integração contínua como um requisito de compatibilidade, não como uma limpeza opcional. ## Conclua uma alteração conferindo o comportamento, não só a compilação Para uma alteração normal: 1. instale dependências somente quando necessário; 2. compile o grafo de dependências relevante; 3. faça a menor edição coerente; 4. recompile os pacotes afetados; 5. execute verificações de tipos delimitadas, formatação, análise estática e testes adequados ao contrato; 6. valide na interface interna; 7. acrescente verificações em ambiente isolado ou equivalentes à produção somente quando forem diretamente relevantes. Para a integração de um renderizador, uma estrutura de desenvolvimento, um compilador de pacotes ou uma extensão, edite o pacote responsável, compile primeiro sem o modo de produção e depois teste por meio de um aplicativo gerado correspondente e do fluxo relevante de execução ou de ponta a ponta. Se uma compilação falhar, atualize as dependências e tente novamente a compilação delimitada antes de aumentar a memória ou alterar a arquitetura. Inspecione as saídas geradas e os caches quando o comportamento no ambiente isolado for diferente do observado na interface interna. Não alegue que a alteração está pronta apenas com base na compilação. A evidência necessária é o menor conjunto que cubra o limite alterado do pacote, os caminhos de compilação compatíveis, o comportamento observável, as premissas entre plataformas e o fluxo de integração diretamente afetado.