Alterar um pacote de servidor público que outros estendem sem quebrar o código deles

## Verificar o que é publicado e deixar segredos de fora Antes de editar, identifique o destino de publicação, a licença, o sistema de módulos, a linguagem, a função no ambiente de execução e o caminho de sincronização do pacote. Trate todos os arquivos dentro de um pacote sincronizado publicamente como conteúdo de publicação, mesmo quando o desenvolvimento ocorrer em um espaço de trabalho privado. - Nunca coloque segredos, comportamentos restritos por licença ou artefatos de teste exclusivamente internos dentro do pacote público. - Mantenha sem interface gráfica os pacotes exclusivos do servidor; não introduza dependências do navegador nem do DOM. - Siga as convenções reais de módulos e linguagem do pacote, em vez de importar padrões de pacotes vizinhos. - Registre os dependentes diretos no espaço de trabalho e presuma que existem outros consumidores externos do pacote. A distribuição pública amplia o alcance do impacto, mesmo quando apenas um dependente é visível no espaço de trabalho. ## Manter funcionando os callbacks antigos e os caminhos de importação profundos Não modernize silenciosamente funções de callback para promises nem funções async. Em código que combina práticas de épocas diferentes, um hook de extensão pode depender do formato do callback, mesmo quando os pontos de chamada próximos são síncronos ou baseados em promises. Antes de alterar uma invocação: 1. Enumere todas as implementações do ponto de extensão. 2. Compare a ordem dos argumentos, o comportamento de retorno, o momento do callback e a semântica de erros. 3. Siga o estilo do arquivo que está sendo alterado. 4. Adicione ou atualize testes para cada formato de invocação compatível. Não renomeie nem mova arquivos de utilitários, middleware ou modelos que pareçam internos até pesquisar imports profundos nos repositórios posteriores. Um import por caminho de código-fonte é uma API pública implícita e pode quebrar sem um aviso do compilador. ## Respeitar a ordem do middleware e os nomes exatos dos hooks Preserve explicitamente as dependências do middleware. A autenticação ou a resolução de token deve ser executada antes das verificações de permissão quando a autorização lê o contexto de usuário já preenchido. Trate alterações de ordem como alterações de contrato, não como limpeza de formatação. Para um middleware novo, reproduza o formato de fábrica estabelecido no pacote, como uma fábrica que recebe o contexto do pacote e retorna um manipulador de solicitações, e registre-o no ponto pretendido da cadeia central. Use o mecanismo existente de hooks de alteração como superfície de extensão. Pesquise todos os nomes e implementações atuais de hooks antes de adicionar um ponto de chamada. Confirme o nome exato, o valor de entrada, o formato do callback ou do retorno e o comportamento padrão; um nome de hook digitado incorretamente pode retornar silenciosamente o valor padrão. Documente todos os novos pontos de extensão onde os implementadores posteriores possam encontrá-los. ## Adicionar migrações novas em vez de editar as já publicadas Siga as abstrações-base estabelecidas, em vez de inventar padrões paralelos. Novos modelos de dados devem usar o plugin de modelo compartilhado ou o formato-base. Novos recursos REST de nível superior devem estender a base de recursos comum e registrar rotas por meio do ponto de entrada central. Trate as migrações de banco de dados já distribuídas como imutáveis e unidirecionais: - nunca edite uma migração existente após a publicação; - adicione uma nova migração numerada para cada correção posterior; - faça com que cada migração seja idempotente; - considere interrupções e execuções repetidas durante a inicialização; - verifique o comportamento em bancos de dados novos e naqueles que já passaram pela migração. Quando pacotes posteriores injetarem campos ou comportamentos de modelos por meio de hooks, audite esses pontos de injeção antes de alterar esquemas, valores padrão, serialização ou hidratação. ## Encontrar os pacotes afetados por uma mudança e testar os dois lados Relacione uma alteração aos seus consumidores antes de implementá-la. Coordene-se com os chamadores posteriores ao alterar middleware de autenticação, tratamento de permissões, limites de sessão, utilitários compartilhados, auxiliares de criptografia, hooks de modelos ou assinaturas de pontos de extensão. Trate auxiliares importados por caminhos profundos como APIs públicas. Trate a propriedade do token em relação à sessão como um limite arquitetônico. Quando um valor for armazenado como referência e hidratado durante a leitura, audite tanto o gravador quanto o processador de desreferenciamento antes de alterar sua representação. Para cada edição transversal: 1. Leia as notas relevantes de arquitetura, dependências e problemas conhecidos. 2. Pesquise implementações e pontos de chamada posteriores. 3. Declare o contrato que deve continuar válido. 4. Teste os dois lados do limite. 5. Documente qualquer alteração intencional de contrato e seu caminho de migração. ## Testar valores que cruzam o limite da máquina virtual Alterações em bundles de máquinas virtuais, camadas de compatibilidade, instâncias de avaliador, limites de recursos ou semântica de erros exigem uma auditoria completa do contrato entre cliente e servidor. Mantenha equivalentes as camadas do host e do ambiente isolado, reconstrua o bundle e verifique se os valores sobrevivem ao limite do ambiente de execução. Não presuma que objetos ativos do banco de dados mantenham identidade ou protótipos após a serialização por meio de um ambiente de execução isolado. Teste identificadores, referências, datas, buffers, erros e valores hidratados nos dois sentidos. Fique atento a alterações no host que afetem todo o processo e sejam causadas por camadas de compatibilidade inicializadas durante o carregamento do módulo. Um contexto de navegador simulado pode criar estado global mesmo quando o pacote deve permanecer sem interface gráfica. Trate o código do bundle excluído da cobertura como uma lacuna de teste conhecida e adicione verificações de execução direcionadas, em vez de presumir que a cobertura comum o comprove. ## Detectar na inicialização os recursos do banco de dados e ter uma alternativa Ofereça suporte a várias implementações de banco de dados sondando seus recursos durante a inicialização. Condicione regras avançadas de ordenação, pipelines de consulta, índices compostos de caminhos aninhados e outros recursos acima da base mínima ao resultado da sondagem, e forneça uma alternativa testada. Nunca deduza compatibilidade pelo nome do produto ou pela string da versão quando o ambiente de execução fornecer um mapa de recursos. Alterações revertidas repetidamente comprovam que o caminho de sondagem e alternativa faz parte do contrato. Quando o comportamento do pacote público depender de um sinalizador de funcionalidade, mas o pacote não puder importar o registro privado, chame o hook de extensão estabelecido com a string de chave exata do sinalizador. Verifique a chave no registro e teste os caminhos habilitado e desabilitado. Não incorpore a lógica do registro privado ao pacote público. ## Rodar os testes, o lint e o build que o pacote realmente tem Defina o estado “aprovado” com base nos scripts que o pacote realmente oferece. Para um pacote somente de JavaScript, isso pode significar o conjunto completo de testes e o linter, sem inventar uma etapa de verificação de tipos que não existe. Execute o build quando a alteração afetar a saída do ambiente de execução incluída no bundle. Registre cada novo arquivo de teste no importador central do conjunto quando a descoberta não for automática; um arquivo de teste não registrado não oferece proteção. Use o filtro de nomes de testes compatível para restringir a investigação, mas execute todo o conjunto obrigatório antes da conclusão. Trate com cuidado os comandos de lint que aplicam correções automáticas e revise o diff. Confirme que os testes, o lint e o build do bundle relevante foram aprovados e preserve avisos que revelem problemas de execução ou compatibilidade. ## Confirmar todo o impacto antes de dar a mudança por concluída Comece pelo contrato afetado, não pelo arquivo mais próximo. Pesquise problemas conhecidos e dependências posteriores, faça a menor alteração compatível e verifique a segurança da publicação antes de informar a conclusão. A revisão final deve confirmar: - nenhum segredo, material restrito ou conteúdo exclusivamente interno entrou no pacote público; - os contratos de callback, hook, import profundo e ordem do middleware continuam válidos; - as migrações são aditivas e idempotentes; - os limites de modelos, referências, máquinas virtuais e recursos de banco de dados foram testados quando afetados; - novos testes estão registrados e os controles de qualidade reais do pacote foram aprovados; - chamadores entre pacotes e a documentação foram atualizados onde necessário; - qualquer alteração incompatível ou de versão principal foi coordenada com todos os destinos de publicação. Não classifique uma alteração como isolada apenas porque a quantidade de dependências no espaço de trabalho é pequena; os consumidores públicos continuam fazendo parte do modelo de risco.