GBR: ADR-0003 Motor Estático de Geração de Sites (gbr_ssg)

• *Status:* Aceito
• *Data:* 2026-07-28

*Contexto:*

A comunidade GleamBR e seus produtos precisam de um Motor de Geração de Sites Estáticos (Static Site Generator - SSG), temporariamente chamado de gbr_ssg. O motor deve ler arquivos de marcação Markdown (com cabeçalhos de metadados Frontmatter), processar seu conteúdo e acoplá-lo a layouts e componentes visuais ricos definidos no pacote packages/gbr_ui usando Lustre. O resultado final deve ser um conjunto de arquivos HTML puros e otimizados prontos para deploy no Cloudflare Pages, garantindo SEO de altíssima qualidade, carregamento rápido e zero custos de execução de servidores na borda.

*Decisão:*

1. *Separação de Componentes:* - **CLI / Executável (apps/gbr_ssg):** Um aplicativo de linha de comando simples responsável por orquestrar a varredura do disco, leitura de configurações, acionamento do motor de conversão e escrita dos arquivos HTML resultantes. - **Motor de Conversão (packages/gbr_ssg_core):** Biblioteca em packages/gbr_ssg_core responsável por ler os arquivos Markdown e transformá-los em estruturas HTML consumíveis pelos layouts Lustre.
2. *Parser de Markdown via Jot:* - Adotar a biblioteca jot (Gleam puro) para parsing de Markdown. Esta escolha garante compatibilidade isomórfica (Erlang & JS), facilitando tanto testes locais na BEAM quanto builds estáticos.
3. *Server-Side Rendering (SSR) via Lustre:* - O motor utilizará lustre/element.to_document_string para serializar os elementos de visualização em HTML plano no momento da compilação estática.
4. *Gerenciamento de Metadados (Frontmatter):* - Os arquivos de entrada em Markdown usarão cabeçalhos YAML delimitados por ---. Esses metadados serão extraídos antes do processamento do corpo do Markdown.

*Alternativas de Implementação Analisadas:*

• **Alternativa A: Parser Puro em Gleam (ex: jot) [ESCOLHIDO]** Prós: Portabilidade e independência absoluta de plataforma. Compila nativamente tanto para Erlang quanto para JavaScript. Contras: A especificação do jot é focada em uma variante simplificada de Markdown, necessitando que extensões complexas específicas sejam tratadas se necessário.

• **Alternativa B: Rust NIF (Rustler) integrando com pulldown-cmark [REJEITADO]** Prós: Desempenho computacional excepcional (CPU-bound) para milhares de posts. Contras: Exige compilador de Rust no CI, aumentando tempo de build e restringindo a execução unicamente à BEAM.

• *Alternativa C: JavaScript FFI (Node.js/Bun Runtime) [REJEITADO]* Prós: Acesso a marked ou markdown-it. Contras: Força o CLI a rodar unicamente com --target javascript.

• **Alternativa D: Erlang FFI com Elixir earmark_parser [REJEITADO]** Prós: Reutilização de ecossistema maduro. Contras: Aumento na complexidade de build de pacotes Elixir no monorepo.

*Consequências:*

• *Positivas:* Permite que todo o design de componentes permaneça fortemente tipado sob a arquitetura Lustre, com builds rápidos e portabilidade.
• *Negativas/Riscos:* Dependência direta do conjunto de recursos suportados pela biblioteca jot para a renderização do corpo Markdown.