O que a compilação verifica

Todos os erros que esta camada realmente teve foram silenciosos: uma coleção que o Content descartou porque o nome não era um identificador JavaScript, uma página que dava 404 porque uma ligação tinha envelhecido, uma navegação que voltava vazia. Nenhum dos três disse nada — a compilação estava verde e o site errado. Por isso correm verificações depois da compilação, todas a ler a mesma coisa: a cache de análise que o Content deixa para trás.

#Porque a gravidade não é uniforme

Um erro custa uma página que ninguém consegue alcançar e que nada no site alguma vez explicaria — uma coleção vazia é um 404 em todas as páginas de uma versão. Um aviso custa qualidade: a página continua a ser apresentada, e uma fonte remota pode desatualizar-se entre um lançamento e o seguinte sem que isso seja culpa desta compilação. Fazer a compilação falhar porque o repositório de outra pessoa avançou tornaria uma compilação verde dependente de um terceiro.

Uma nota não custa nada: é um estado do site, não um defeito nele. Uma página por traduzir não é um erro, e reportá-la como aviso ensinaria toda a gente a passar por cima dos avisos.

#Secções geradas

Uma secção gerada é verificada como qualquer outra coleção, nas suas próprias palavras. O que chega a este relatório é uma de três coisas:

• o artefacto não estava lá nessa ref, pelo que a secção não foi construída;
• o tipo não leu nada dele, pelo que a secção reclama URL e não serve nenhum;
• o tipo passou por cima de alguma coisa — um $ref que não resolve num documento OpenAPI, um título de changelog que parece uma release mas não é analisado como tal e por isso passou a fazer parte da release acima dele.

As três são avisos, e isso não é um compromisso. Tudo o que um artefacto local pode ter de errado — um caminho que não existe, um ficheiro que o tipo não consegue sequer ler, uma opção que desconhece — já faz a compilação falhar enquanto a configuração é carregada, muito antes de este relatório existir: a configuração do próprio site é um erro que a compilação não pode carregar. O que sobra aqui é ou um artefacto remoto, que pode legitimamente ter desatualizado entre lançamentos, ou uma página que foi desenhada com algo em falta.

#O relatório de traduções

Uma linha por idioma, em cada compilação:

[duxt] translations
[duxt]   de: 118/121 pages, 3 behind the original
[duxt]     "docs/guides/deploying.md" has no de translation.
[duxt]     "docs/de/concepts/sources.md" has not moved since the original changed.

O segundo número precisa de history: true na fonte — as datas vêm do git, e uma fonte que não pediu o seu histórico não tem nenhuma. Sem ele o relatório conta a cobertura e nada diz sobre o desfasamento, em vez de o adivinhar a partir da ausência.

Existe por causa de uma falha concreta. O OpenCode traduziu a sua documentação para dezassete idiomas com um agente em CI, desligou o fluxo de trabalho, e em lado nenhum ficava dito que as traduções tinham deixado de se mexer. A camada já sabe, por página, que idiomas a carregam e quando cada ficheiro mudou pela última vez; um relatório é o que transforma isso em algo que alguém vê.

#O mesmo relatório, como comando

Os achados vivem em dois sítios difíceis de entregar a alguém: um registo de compilação que já desapareceu do ecrã, e painéis de devtools que só existem dentro de um servidor de desenvolvimento a correr. O duxt-report é o terceiro — os mesmos dados em Markdown no stdout. Vem com o pacote, por isso estender a camada é tudo o que é preciso para o ter.

pnpm exec duxt-report            # Markdown
pnpm exec duxt-report --json     # os mesmos dados, sem desenhar

Lê o app.config.ts do site, os artefactos ao lado dele e as páginas a partir da cache de análise do Content — sem servidor, por isso corre em CI e num pipe. Sai com 1 num erro e com 0 em avisos, que é a mesma regra de gravidade que a compilação segue.

Três painéis não têm equivalente aqui, e de propósito: o índice de pesquisa, o depurador de caminhos e a listagem da cache são perguntas sobre um processo em execução, e respondê-las a partir de fora seria adivinhar.

#O que as verificações sabem e tu não

• Uma colisão de pastas só é um problema enquanto um prefixo está ativo. Uma pasta de documentação chamada v2 está bem num site sem versões e é inalcançável num versionado, porque o prefixo ganha. A compilação sabe qual é o caso, e a mensagem nomeia o ficheiro e oferece a solução.
• Uma ligação é resolvida como o tema a resolve. Um caminho absoluto escrito numa página é relativo à fonte dessa mesma página, por isso é tentado primeiro sob o prefixo da fonte e depois nu. Um verificador que fizesse apenas a forma nua reportaria todas as ligações corretas de um site multirrepositório.
• Uma ligação é resolvida no seu próprio idioma. Todos os idiomas de uma fonte servem caminhos de conteúdo idênticos — a locale fica à frente do URL, não na árvore de conteúdo — e as âncoras derivam do texto dos títulos, pelo que um título alemão tem uma âncora alemã. Uma verificação que resolvesse só pelo caminho confrontaria uma ligação alemã com títulos ingleses e reportaria cada âncora correta de um site traduzido. Uma ligação para uma página que um idioma não carrega recorre ao original, que é o que o site faz.
• URL externos não são verificados. Verificar um poria a rede dentro da compilação, e um servidor alheio inacessível não é razão para a tua documentação não ser publicada.

#Escreve as ligações como caminhos de documentação absolutos

/concepts/sources, não ../2.concepts/2.sources.md. O prefixo sob o qual uma página é servida é decidido na compilação, por isso escrever caminhos sem ele é o que permite que o mesmo Markdown sirva /guides/deploying num site e /acme/v2.0.0/guides/deploying noutro. É também a única forma que o verificador de ligações vê.