4 diagramas com texto estourando a borda essa semana: como paramos de corrigir na mão

O comentário no topo do nosso gerador de diagrama diz por que ele existe: "diagrama gerado por IA erra texto e sai diferente a cada chamada, então não dá para garantir que a versão pt, en e zh sejam o mesmo desenho". A gente trocou IA por código exatamente pra resolver isso. Só que código também tem bug, e o nosso ficou ali, sem ninguém consertar de vez, por pelo menos 6 dias: quatro diagramas publicados essa semana saíram com nota de texto cortada na borda do card, corrigida à mão, sempre do mesmo jeito.

Por que os diagramas do blog não são gerados por IA?

Porque IA generativa desenha diferente a cada chamada. Um artigo sai em três idiomas (pt, en, zh), e cada versão precisa ter exatamente a mesma geometria, só o texto muda. Gerador de imagem por IA não garante isso: às vezes troca a cor, às vezes erra a palavra, às vezes desenha uma caixa a mais de um lado. A solução foi tirar o desenho da IA e colocar em código: um script Python (render.py, com a biblioteca Pillow) lê um arquivo de especificação em JSON e desenha a mesma estrutura nas três línguas, mudando só as strings.

Como o gerador funciona, na prática?

Cada diagrama é um arquivo specs/<nome>.json, com um layout (fluxo, comparativo ou capa_vs) e uma chave locales com pt, en e zh dentro. Termo que não traduz (comando, flag, nome de variável) fica na raiz do spec; o que traduz fica em locales. Rodar é isso:

python3 render.py specs/nome-do-diagrama.json pt en zh

Sai um PNG por idioma em out/, com a mesma geometria e as mesmas cores, só trocando a string.

Qual bug apareceu pelo menos 4 vezes em 6 dias?

Todo texto do diagrama era desenhado com uma chamada direta a d.text(), numa posição fixa, sem nenhuma verificação de largura. O card de cada passo tem uma largura calculada dividindo o espaço disponível pelo número de passos; se a nota daquele passo fosse mais comprida do que essa largura, ela simplesmente continuava desenhando pra fora do card. Ninguém tinha notado até o texto ficar longo o bastante, e aconteceu de novo, e de novo:

Em duas dessas rodadas o próprio registro já dizia "mesmo bug já visto em posts anteriores": o número real de vezes que isso aconteceu é maior do que essas 4 linhas, essas são só as que ficaram com data e post associados no nosso log de execução. A correção sempre foi a mesma: abrir a nota, contar caractere no olho, encurtar, gerar de novo, e torcer pra versão em inglês e em chinês também couberem, porque cada idioma usa um tamanho de texto diferente pra dizer a mesma coisa.

Como corrigimos, pra não precisar de uma quinta vez?

Em vez de confiar no olho, o gerador agora mede antes de desenhar. Uma função nova, ajusta(), usa d.textlength(), a mesma função do Pillow que já centralizava o "vs" nas capas da trilha comparativa, pra saber, em pixel, se o texto cabe na largura disponível. Se não couber, uma busca binária acha o maior pedaço do texto que ainda cabe e completa com reticências:

def ajusta(s_, fo, maxw):
    if maxw <= 0 or d.textlength(s_, font=fo) <= maxw * S:
        return s_
    lo, hi = 0, len(s_)
    while lo < hi:
        mid = (lo + hi + 1) // 2
        if d.textlength(s_[:mid].rstrip() + "…", font=fo) <= maxw * S:
            lo = mid
        else:
            hi = mid - 1
    return (s_[:lo].rstrip() + "…") if lo > 0 else "…"

Aplicado nos quatro pontos que já estouraram alguma vez: título e nota de cada passo, rótulo do ramo de erro e cada linha de nota do ramo. Não é mais preciso adivinhar quantos caracteres cabem em cada idioma: o código mede o pt, o en e o zh, cada um com sua própria fonte, e cada um decide sozinho se precisa cortar.

O que isso não resolve: o texto continua numa linha só e é cortado, nunca quebra em duas linhas. Uma nota muito comprida perde informação em vez de ocupar mais espaço vertical no card. Resolve o problema real (texto vazando pra fora do card), não é a versão definitiva de um sistema de texto.