Alterar um monorepositório grande e tipado sem quebrar outros pacotes

## Encontrar o pacote responsável antes de editar Comece pela raiz do repositório e identifique o pacote responsável pelo comportamento solicitado. - Diferencie as bibliotecas centrais, as integrações com estruturas de desenvolvimento, os aplicativos implantáveis, os exemplos e as ferramentas internas. - Leia o guia da raiz e o guia de pacote mais próximo; o guia mais específico rege o comportamento do pacote. - Confirme o ambiente de execução fixado, o gerenciador de pacotes, a organização do espaço de trabalho e a construção necessária antes de executar comandos de desenvolvimento. - Não presuma que exista um servidor de desenvolvimento na raiz. Inicie o pacote responsável ou use o filtro do espaço de trabalho que inclua as dependências a montante dele. - Antes de alterar um consumidor, rastreie os tipos, utilitários, estilos e recursos gerados compartilhados até o pacote canônico correspondente. - Mantenha a alteração no menor pacote responsável, a menos que o contrato público realmente abranja vários pacotes. ## Seguir as regras de construção e dependências de cada pacote Escolha o caminho de construção que corresponda ao pacote, em vez de impor uma única ferramenta a todo o espaço de trabalho. - Use uma construção orientada ao compilador para bibliotecas puramente tipadas e um empacotador de componentes para pacotes de interface. - Externalize as dependências na saída da biblioteca; use uma construção autônoma explícita somente quando o produto final precisar incluir suas dependências de execução. - Mantenha as dependências internas no protocolo do espaço de trabalho e obtenha as versões compartilhadas de terceiros no catálogo central de versões. - Importe os tipos compartilhados pelos pontos de entrada documentados, não pela raiz ampla de um pacote. - Quando um pacote publicar vários formatos, verifique cada saída declarada e suas declarações de tipos. - Trate a configuração de construção, os arquivos de bloqueio, as configurações compartilhadas do compilador e os catálogos do espaço de trabalho como arquivos de amplo impacto que exigem validação mais extensa. ## Reutilizar utilitários compartilhados antes de escrever código novo Pesquise no pacote compartilhado de funções auxiliares antes de escrever um utilitário novo. Verifique as funções auxiliares existentes para matrizes, objetos, cadeias, URL, HTTP, JSON, Markdown, erros, arquivos, filas, formatação, expressões regulares e testes. Reutilize diretamente uma função adequada. Adicione uma função nova ao pacote compartilhado somente quando nenhum comportamento existente corresponder e vários consumidores puderem usar a nova abstração. Não crie implementações quase duplicadas em pacotes de funcionalidades. Se o comportamento existente for próximo, mas não exato, compare os contratos, os casos extremos, o impacto no empacotamento e os locais de chamada antes de decidir entre ampliá-lo ou manter uma função local específica do domínio. ## Evitar `any` e tipar as funções e as props dos componentes Escreva código que mantenha útil a inferência e torne explícitos os contratos públicos. - Prefira aliases de tipos e uniões de literais de cadeia a interfaces e enumerações quando esse for o padrão da base de código. - Dê às funções tipos de retorno explícitos, use `unknown` em vez de `any`, marque as importações exclusivas de tipos e adote vínculos imutáveis por padrão. - Mantenha as importações diretas; evite arquivos agregadores, exceto em pontos de entrada de pacotes criados deliberadamente, e evite reexportações com curingas. - Nunca suprima erros de tipos de forma genérica. Use uma diretiva de erro esperado somente com uma justificativa que prove que o erro é intencional. - Trate todas as promessas e não marque uma função como assíncrona, a menos que ela espere alguma operação. - Em arquivos de componentes, atribua tipos às propriedades e aos eventos, defina valores padrão por desestruturação, mova a lógica de template não trivial para valores calculados e siga a ordem de configuração estabelecida. - Escreva comentários e documentação de API para explicar por que uma restrição existe, não para repetir o código. ## Testar primeiro o pacote afetado, não o repositório inteiro Execute o menor escopo de testes que comprove a alteração. 1. Coloque os testes unitários ao lado do código-fonte e nomeie a suíte de nível superior de acordo com o arquivo. 2. Prefira asserções comportamentais e funções puras; reduza ao mínimo as simulações e evite testar a estrutura da marcação ou os detalhes de estilo quando o comportamento do usuário for o contrato. 3. Execute uma vez o pacote afetado com um filtro de caminho explícito. Use o modo de observação somente durante o desenvolvimento ativo. 4. Execute testes de integração para adaptadores alterados e testes de ponta a ponta para jornadas de usuário afetadas. 5. Inicie os serviços locais de teste necessários e aguarde que estejam prontos antes dos testes que dependam deles; testes unitários não devem usar a rede real. 6. Execute a suíte completa do monorepositório somente para uma verificação final e intencional de integração ou uma alteração ampla de contrato compartilhado. Trate separadamente as falhas anteriores sem relação com a alteração: reproduza-as fora do escopo da mudança, relate-as como tais e não as classifique incorretamente como êxito do ambiente nem como falha causada pela alteração. ## Rodar lint nos arquivos alterados e checar tipos nos pacotes afetados Determine o conjunto de arquivos alterados e aplique cada ferramenta somente à sintaxe pela qual ela é responsável. - Execute o analisador estático e o formatador da linguagem tipada nos arquivos tipados alterados. - Execute o analisador de componentes e o formatador geral nos arquivos alterados de componentes, documentação, dados, estilos e configuração. - Verifique os tipos de cada pacote afetado por meio do respectivo script do espaço de trabalho. - Procure exportações, arquivos e dependências não utilizados antes de abrir ou atualizar uma revisão. - Exija que todas as verificações relevantes de análise, formatação, tipos, testes e código não utilizado sejam concluídas sem erros. Não use um comando para todo o repositório quando um filtro de pacote fornecer um sinal mais forte com menos ruído sem relação. Amplie a validação quando a configuração fundamental mudar ou quando a análise de dependências mostrar vários consumidores posteriores. ## Escrever títulos de revisão no formato type(scope) e adicionar um changeset Use um ramo dedicado e descrições convencionais da alteração no tempo presente, com o escopo do pacote relevante. - Dê aos títulos das revisões a forma semântica `type(scope): subject`, usando um tipo de alteração permitido. - Coloque as referências a tíquetes e questões na descrição da revisão com a palavra-chave correta de encerramento ou de não encerramento; não esconda nos comentários os identificadores de rastreamento obrigatórios. - Adicione uma seção específica de tíquetes quando forem fornecidos links de rastreamento. - Para alterações publicáveis em pacotes, integrações ou aplicativos, examine o estado das notas de versão e adicione um conjunto de alterações de nível patch ou minor quando a versão precisar avançar. Não introduza uma elevação major pelo fluxo de trabalho habitual. - Mantenha as soluções temporárias visíveis com um TODO e explique a condição para removê-las. - Nunca faça commit de alterações com falhas conhecidas de análise, tipos, testes ou exportações não utilizadas. ## Conferir mudanças de interface com capturas de tela, no ambiente de testes onde elas aparecem Construa os pacotes a montante e depois escolha o ambiente de testes que exponha mais diretamente o comportamento alterado. - Use o catálogo de componentes para controles básicos, a superfície de documentação para renderização e navegação e a superfície do cliente para edição, autenticação, solicitações e respostas. - Verifique superfícies secundárias quando componentes compartilhados, temas, renderização de sintaxe ou ícones se propagarem para vários produtos. - Capture imagens de antes e depois para a interface alterada, imagens com contexto para o comportamento novo e uma gravação curta para as interações. - Use nomes descritivos para os artefatos e incorpore as evidências em uma seção visual específica da descrição da revisão. - Se uma alteração afetar várias superfícies ou disposições, capture cada resultado materialmente diferente em vez de tratar uma única imagem como prova universal. Os artefatos visuais complementam os testes automatizados; não substituem as asserções de comportamento, as verificações de acessibilidade nem a validação de tipos. ## Usar os termos exatos do projeto e relatar só as verificações feitas Use o glossário do projeto de forma coerente no código, na documentação, nos testes e no texto das revisões. Diferencie um formato de protocolo de uma descrição de API, um esquema de dados de um documento, a desreferenciação da resolução e o empacotamento dessas duas últimas operações. Antes de concluir: - revise a diferença final e confirme que todos os arquivos alterados pertencem ao escopo pretendido; - verifique, conforme aplicável, a construção, os testes, a análise, a formatação, os tipos, a procura de código não utilizado e as evidências visuais; - confirme que os pontos de entrada dos pacotes, os catálogos de dependências e os conjuntos de alterações correspondem à implementação; - liste qualquer verificação que não pôde ser executada e preserve a evidência exata da falha; - não afirme ter obtido um resultado de todo o monorepositório quando somente uma verificação com escopo de pacote foi executada. Relate os pacotes afetados, os comandos executados, os resultados diretos, os riscos residuais e qualquer trabalho adiado intencionalmente.