ADR 0009: Política de Zero Template Literals no Módulo Admin

Status

Aceito

Contexto

Durante o desenvolvimento da versão v1.2.5, o processo de build do Cloudflare Wrangler (via Esbuild) começou a falhar sistematicamente ao processar o arquivo src/routes/admin.ts. O erro reportado era "Unterminated string literal", mesmo com a sintaxe TypeScript aparentemente correta.

Investigações revelaram que o parser do Esbuild, ao lidar com arquivos grandes contendo múltiplos tagged template literals (especificamente o sql do Drizzle ORM) e interpolações complexas (${...}), tornava-se instável. Além disso, múltiplas edições incrementais via ferramentas de IA introduziram bytes residuais ou caracteres invisíveis que corromperam a estrutura de strings do arquivo.

Decisão

Adotamos uma política estrita de Zero Template Literals para o arquivo src/routes/admin.ts (e potencialmente outros módulos de rotas complexas):

1. Consultas SQL: Substituir sql${...}`` por sql.raw() com concatenação de strings clássica.
2. Mensagens e Logs: Substituir ${variable} por '...' + variable + '...'.
3. Higiene de Arquivo: Em caso de erros de parsing persistentes, o arquivo deve ser re-escrito integralmente via comando de terminal (cat << EOF) para garantir a purga de metadados de edição corrompidos.

Consequências

• Positivas:
  • Build 100% determinístico e estável no Cloudflare Workers.
  • Eliminação de erros fantasmas de "Unterminated string literal".
  • Maior facilidade para o parser do Esbuild processar o arquivo.
• Negativas:
  • Perda leve de legibilidade visual nas consultas SQL (embora compensada pela segurança do build).
  • Necessidade de cuidado redobrado com escapes manuais em strings concatenadas (minimizada pelo uso de sql.raw em partes fixas).

Referências

• Incidentes de Build v1.2.5.
• Documentação Drizzle: sql.raw().