Imite o comportamento de outro framework web com uma camada de compatibilidade

## Use os testes e o código do framework de referência como especificação Trate a compatibilidade como um problema de evidências. Os testes e a implementação do framework de destino definem o comportamento esperado de modo mais confiável do que a intuição. Para cada recurso ou correção de erro: 1. Pesquise amplamente nas suítes originais de testes unitários e de ponta a ponta, incluindo nomes relacionados, erros, entradas inválidas e casos extremos. 2. Leia a implementação correspondente para entender a ordem, os valores padrão e o comportamento em caso de falha. 3. Pesquise issues ou discussões de projeto anteriores quando o código não explicar se um comportamento é intencional. 4. Adapte os casos relevantes antes de implementar a alteração e vincule cada adaptação ao respectivo teste original. 5. Documente as evidências na descrição da alteração. Use um shallow clone local para pesquisar rapidamente o código-fonte e os testes. Use a pesquisa remota de código somente quando o clone não estiver disponível ou a questão exigir uma discussão atual. Se a camada de compatibilidade precisar diferir intencionalmente por motivos de segurança, implantação ou plataforma, registre essa decisão de forma explícita. Nunca permita que uma divergência acidental se passe por um recurso. ## Escreva primeiro um teste que falhe e corrija juntos todos os pontos de entrada Primeiro escreva um teste focado que falhe e depois implemente a menor alteração que satisfaça o contrato verificado. - Execute o arquivo de teste do subsistema alterado e os testes diretamente acoplados. - Adicione entradas de fixture para o comportamento de integração; preserve os exemplos para demonstrações destinadas aos usuários. - Use filtros de nome de teste durante as iterações. - Deixe a CI executar a suíte completa, a menos que a alteração afete o roteamento compartilhado, a infraestrutura de build, os módulos virtuais ou os helpers de teste comuns. - Quando a infraestrutura compartilhada mudar, amplie a validação local somente para os escopos transversais afetados. Associe a validação à responsabilidade: shims precisam de testes de shim, roteamento precisa de testes de ordem de rotas, cache precisa de testes de cache, e alterações de build ou implantação precisam de testes de build. O tratamento de solicitações costuma existir em pontos de entrada separados para desenvolvimento, produção, renderização no servidor e edge. Verifique todas as implementações responsáveis pelo mesmo comportamento e corrija as lacunas de paridade na mesma alteração, em vez de deixar duplicações conhecidas para trás. ## Passe os dados da solicitação entre ambientes e mantenha enxuto o código gerado Ambientes separados de build ou renderização podem ter grafos e estados de módulos independentes. Nunca pressuponha que definir o estado de uma solicitação em um ambiente altere outro. - Transmita explicitamente pathname, parâmetros, cabeçalhos, cookies e outros contextos da solicitação através dos limites entre ambientes. - Inicialize o contexto imediatamente antes da renderização e limpe-o depois. - Mantenha o estado com escopo de solicitação e as pequenas fachadas públicas separados das implementações pesadas. - Verifique tanto o consumo por streaming quanto o momento da limpeza. Os módulos de entrada gerados devem conter somente imports específicos de rotas, manifests e conexões enxutas. Mova a orquestração de solicitações, a política de cache, o despacho de métodos, os redirecionamentos, o tratamento de erros, a mesclagem de cabeçalhos e outros comportamentos testáveis para módulos tipados normais. Teste diretamente os helpers extraídos com testes unitários. Os testes de código gerado devem verificar a delegação e as conexões, em vez de comparar grandes strings de implementação. Mantenha um limite claro de responsabilidade entre o plugin subjacente do bundler e a camada de compatibilidade. O plugin pode ser responsável por transformações, serialização, builds para vários ambientes, tratamento de CSS e inicialização da hidratação, enquanto a camada de compatibilidade é responsável por roteamento, ciclo de vida das solicitações, composição do layout, navegação, cache e shims de API. ## Normalize caminhos de arquivos e faça o build pelo pipeline completo de vários ambientes Os caminhos do sistema de arquivos usados como IDs de módulo ou imports gerados precisam de uma única política canônica de separadores em todos os sistemas operacionais. - No código-fonte, use uma abstração de caminhos que preserve a semântica nativa e retorne identificadores canônicos. - Normalize somente valores de origem externa, como diretórios de trabalho do processo, módulos resolvidos, caminhos reais, saída de glob e IDs informados pelo bundler. - Não normalize repetidamente valores já produzidos pela camada canônica de caminhos. - Mantenha a sanitização de barras invertidas de URL separada do tratamento de caminhos do sistema de arquivos. - Documente e submeta ao linter qualquer exceção realmente necessária para caminhos nativos. Os testes devem construir entradas com APIs de caminho nativas para que o Windows forneça barras invertidas reais. Coloque somente as saídas esperadas na forma canônica. Testes multiplataforma construídos inteiramente com barras normais não conseguem detectar uma regressão de normalização no Windows. Os builds de produção devem usar o pipeline completo do builder de vários ambientes do plugin do framework. Uma chamada genérica de build para um único ambiente pode ignorar silenciosamente as fases obrigatórias de server, renderer e client. Quando a cadeia de ferramentas mudar de versão principal, prefira as famílias atuais de opções de transformer, dependency optimizer e bundler. Trate nomes de opções legados como alvos de migração. Módulos virtuais também precisam de tratamento explícito para IDs com prefixo de raiz, prefixos null já resolvidos e imports absolutos quando não existe uma localização física do módulo. ## Mantenha leves as solicitações comuns e defina o comportamento do cache Mantenha os ambientes de execução específicos de cada recurso fora do caminho comum das solicitações. - Condicione o comportamento opcional usando metadados baratos da solicitação ou da rota antes de importá-lo dinamicamente. - Use imports somente de tipos quando o código em tempo de execução não for necessário. - Filtre os hooks do bundler antes da execução dos handlers de JavaScript, excluindo dependências, ambientes de execução gerados, prebundles e alvos sintáticos impossíveis. - Mantenha módulos leves de estado e registro separados das implementações de cache, navegação ou renderização. - Reutilize chaves de cache calculadas e valores derivados da solicitação. - Eleve expressões e tabelas imutáveis. - Mova a análise determinística e a seleção de assets para o momento do build quando possível. Não adicione cache até que responsabilidade, invalidação e paridade entre ambientes de execução estejam explícitas. Um grafo de módulos menor não é vantajoso se causar código obsoleto, condições diferentes entre ambientes ou bundles de plataforma corrompidos. Mantenha simples os handlers de armazenamento e coloque acima deles a política de regeneração incremental. Defina separadamente o comportamento stale-while-revalidate, a regeneração single-flight, os metadados de revalidação e a invalidação por tags. Entradas cujo prazo expirou podem ser retornadas como obsoletas enquanto a regeneração é executada; entradas invalidadas explicitamente devem ser removidas. Torne declarativa a seleção do backend, mantenha um padrão seguro e registre adaptadores opcionais antes do primeiro uso. ## Processe as solicitações na mesma ordem do framework de referência Modele o ciclo de vida das solicitações do framework de destino como um contrato ordenado: 1. Os cabeçalhos de configuração estática são avaliados em relação à solicitação original. 2. Os redirecionamentos estáticos são avaliados em relação à solicitação original. 3. O middleware é executado e pode reescrever, redirecionar ou modificar cabeçalhos. 4. As reescritas anteriores ao sistema de arquivos são avaliadas em relação ao estado posterior ao middleware. 5. As rotas estáticas e do sistema de arquivos são resolvidas. 6. As reescritas posteriores ao sistema de arquivos são executadas. 7. As rotas dinâmicas são resolvidas. 8. As reescritas de fallback são executadas. Não mova uma etapa apenas porque a resposta final parece equivalente. As correspondências condicionais podem mudar quando o middleware altera a solicitação. Registre as lacunas de paridade conhecidas em vez de ocultá-las. Preserve distinções intencionais, como quais ativos estáticos ignoram o middleware e quais arquivos públicos passam por ele. Para APIs em evolução, ofereça suporte a padrões de acesso antigos e novos somente quando o contrato de compatibilidade exigir ambos. Por exemplo, uma promise ampliada com campos resolvidos pode aceitar tanto o acesso a parâmetros com await quanto o acesso direto. Bibliotecas de terceiros que usam imports de APIs públicas podem funcionar por meio de aliases ou da normalização de extensões. Bibliotecas que dependem de plugins de build ou APIs internas exigem integração explícita; apenas instalá-las e importá-las não é suficiente. ## Não contorne o lockfile e faça merge só por pull requests aprovados nas verificações Nunca contorne um lockfile congelado durante uma instalação não assistida. Se a resolução de dependências realmente exigir a alteração do lockfile, pare e peça ao usuário que realize ou autorize essa operação. Versões exatas e hashes de integridade são um limite da cadeia de suprimentos. Nunca faça push diretamente para a branch padrão protegida, contorne a proteção da branch nem force um merge administrativo. Use esta sequência: 1. Crie uma feature branch com escopo específico. 2. Faça a menor alteração coerente e execute verificações focadas. 3. Faça commit conforme a convenção de mensagens exigida pelo repositório. 4. Faça push da branch e abra um pull request. 5. Aguarde todas as verificações obrigatórias de formato, tipos, testes unitários e testes de ponta a ponta passarem. 6. Corrija as falhas em vez de contorná-las. 7. Faça o merge pelo método aprovado e remova a branch. Deixe a automação de lançamento derivar metadados do changelog a partir de conventional commits. Use mecanismos documentados de substituição somente para uma reclassificação retroativa deliberada; não edite manualmente os artefatos de lançamento gerados. Em grandes refatorações, use pequenas alterações empilhadas, cada uma extraindo um limite coeso, adicionando testes focados de helpers e atualizando as verificações de delegação. A CI para contribuições não confiáveis deve ser executada sem segredos e com permissões somente de leitura. Workflows de preview que usam segredos devem ignorar forks, a menos que um mantenedor autorizado os acione explicitamente por meio de um comando protegido por identidade. Cada exemplo implantado precisa ser registrado na matriz de build e ter um teste de fumaça que verifique a rota, o status e o conteúdo esperados. O lançamento ou a implantação só estará concluído depois que as verificações obrigatórias e as evidências pós-implantação forem aprovadas.