Pular para conteúdo

AUR-588: documentação visual e reproduzível

Medido antes (base 2c4ee9ac)

  • O único check em navegador, tests/docs/site.test.cjs (job "Documentation browser checks"), abria só a página legada docs/site/index.html. O site MkDocs (navegação, busca, tutoriais, guia de extensão) não era aberto por navegador nenhum no CI; a imagem mcr.microsoft.com/playwright:v1.58.2-noble era referenciada só pela tag.
  • Os tutoriais mostravam apenas logs de texto; não havia captura de tela.
  • O tema Material carregava fontes do Google Fonts (requisição externa) e a busca separava termos só por espaço e hífen: "deliberacao" (sem acento) não achava nada, porque a palavra só aparece em caminhos como demo/tutoriais/deliberacao/run.sh.

O que mudou

  • scripts/docs/capturas.sh (entrada) e scripts/docs/capturas.cjs (roda na imagem Playwright fixada por digest em scripts/docs/playwright.lock, via docker no host, como o usuário que chama, HOME=/tmp, pacote npm playwright@1.58.2 em cache fora do checkout):
  • secoes: reescreve, entre marcadores, a seção "Como fica" no fim de cada docs/tutorials/<t>.md, com uma captura por vista de cada caso (casos = demo/tutoriais/<t>/out/*.log);
  • casos: para cada caso, renderiza o terminal (ANSI → HTML a partir de out/<caso>.log), o comentário do PR (o último bloco ## Code Review Summary do log, Markdown renderizado) quando o caso publica, e os status checks (linhas status publicado: context=... state=...) quando existem; largura fixa de 900 px;
  • scripts/docs/build.sh (--strict) e paginas: serve ./site em 127.0.0.1 (servidor Node no próprio container) e captura cada página de capacidade (index, configuration, gate-corporativo, architecture, extensao e os 18 tutoriais) em desktop 1280×800 e mobile 390×844;
  • manifesto docs/assets/capturas/capturas.json. Determinismo: viewport fixo, deviceScaleFactor 1, reducedMotion, animações e transições desligadas, colorScheme claro, antialiasing em tons de cinza (--disable-lcd-text), e toda requisição fora do servidor local é abortada. Uma execução completa apaga docs/assets/capturas/ antes, então caso removido não deixa imagem órfã.
  • scripts/docs/png-sem-perda.cjs: otimização sem perda (paleta exata quando a imagem tem até 256 cores, deflate máximo; regrava só se ficar menor). Total: 229 PNGs, cerca de 12 MB (terminal típico de 370 KB → 113 KB). Não foi preciso reduzir viewport nem qualidade.
  • Manifesto: uma entrada por linha (legível por awk/sed no aceite selado) com imagem, tipo, insumo, insumo_sha256, playwright e comando. Não registra o digest do PNG nem a data da geração: o card pede "a data da geração" e também que duas execuções produzam o mesmo manifesto; as duas coisas são incompatíveis, e a reprodutibilidade venceu (a data está no commit). O PNG pode variar byte a byte entre máquinas (fontes, GPU); o que se confere é o insumo.
  • scripts/docs/capturas-check.sh: conferência sem docker (bash, awk, sed, sha256sum; compatível com o busybox do perfil selado): imagem Playwright do manifesto = playwright.lock; toda imagem do manifesto existe e o digest do insumo bate; toda captura referenciada por uma página existe e está no manifesto; nenhum PNG fora do manifesto; toda página de capacidade tem desktop e mobile; todo tutorial tem "## Como fica" com captura de cada caso; docs/index.md e docs/extensao.md referenciam capturas.
  • tests/docs/mkdocs.test.cjs: abre o site MkDocs construído (servidor local): toda entrada da navegação primária responde 200; a busca retorna resultados para "engine", "gitleaks", "deliberacao", "skill", "ContextProvider" e "excecao proposta"; todas as páginas da navegação abertas em 390 px sem rolagem horizontal; toda imagem em /assets/capturas/ carrega (naturalWidth > 0, 200) e está no manifesto; nenhum erro de console, pageerror ou requisição externa.
  • mkdocs.yml: theme.font: false (fontes do sistema, sem CDN) e search.separator que também separa /, ,, :, (), crases e ponto não seguido de dígito.
  • .github/workflows/ci.yml (job "Documentation browser checks"): constrói o site, roda capturas-check.sh e, na imagem Playwright pinada por digest (a mesma do lock), site.test.cjs e mkdocs.test.cjs. .github/workflows/docs.yml: roda capturas-check.sh antes do build e dispara também em demo/tutoriais/**.
  • docs/index.md e docs/extensao.md: seção "Como fica" com capturas; os 18 docs/tutorials/*.md: seção "Como fica" gerada; docs/README.md: nota sobre capturas.sh.

Prova

Comandos com cwd no worktree; últimas linhas reais.

  • AC-001 (bash tests/acceptance/AUR-588.sh full, host com docker): roda capturas.sh duas vezes numa cópia; mesmo manifesto entre as execuções e igual ao versionado, mesmo conjunto de arquivos, build sem warning. full AC-001: two runs, same manifest (= committed) and same 230 files. No worktree, duas execuções seguidas também deram PNGs byte a byte iguais (mesma máquina); isso não é exigido entre máquinas.
  • AC-002: AUR-588.sh AC-002 → AC-002: 18 tutorials with "Como fica"; index and extension guide reference captures; bash scripts/docs/build.sh (--strict) → Documentation built, 0 warnings.
  • AC-003: full → full AC-003: PASS: 188 nav pages 200, 6 search terms, 183 captures in the manifest, no console error, no horizontal scroll at 390px. O comando exato do job de CI (imagem por digest, npm install playwright@1.58.2, site.test.cjs && mkdocs.test.cjs) passou localmente. Busca: engine 10, gitleaks 10, deliberacao 2, skill 10, ContextProvider 6, excecao proposta 10 resultados exibidos.
  • AC-004 (selado): ./.board/bin/oci-run --profile go-unit-offline-v1 --card AUR-588 → exit_code: 0, AC-004: capturas-check: ok (229 capturas no manifesto, 183 referencias), AUR-588/all/pass.
  • MUT-001: remover docs/assets/capturas/gate/status-pr-status.png numa cópia → capturas-check: docs/assets/capturas/gate/status-pr-status.png: captura referenciada ausente (AC-004 vermelho); no full, o mesmo arquivo removido do site construído → full MUT-001: Chromium RED: AssertionError [ERR_ASSERTION]: capture does not load: /assets/capturas/gate/status-pr-status.png (AC-003 vermelho).
  • MUT-002: acrescentar uma linha a demo/tutoriais/gate/out/status-pr.log numa cópia → insumo demo/tutoriais/gate/out/status-pr.log mudou sem regenerar a captura (digest diverge do manifesto; rode scripts/docs/capturas.sh).
  • AC-005 (auto-checagem do builder; o revisor repete): com a skill webapp-testing (Playwright Python na imagem pinada, with_server.py servindo ./site), abri o site construído e três capturas dentro das páginas:
  • tutorials/gate/, seção "Como fica": título, parágrafo do manifesto e o primeiro caso, achado-deterministico, com o terminal mostrando $ aurumcode review --base main --politica /policy --seguranca ... e as linhas "no LLM provider configured", idênticas ao início de demo/tutoriais/gate/out/achado-deterministico.log; o índice lateral lista "Como fica" e os casos.
  • extensao/, engine-no-gate-terminal.png (868×557): mostra policy gate: exemplo:marca ... origem exemplo, o resumo com "Changes requested", exit_code=3 e sarif result: exemplo:marca app.py:2 origin=exemplo, linha a linha como demo/tutoriais/extensao/out/engine-no-gate.log.
  • tutorials/gate/, status-pr-status.png: seis status na ordem publicada (review success, policy-gate success, review failure, policy-gate failure, review success, policy-gate failure), os mesmos seis status publicado: de demo/tutoriais/gate/out/status-pr.log; e tutorials/revisao/, com-provedor-comentario.png: o comentário renderizado com "Verdict: Changes requested", error 1 / warning 0 / info 0 e app.go, como no log.
  • Regressão: no container compartilhado, AUR-560.sh all → AUR-560/all/ok; AUR-561..564.sh all → AC-002-MUT-001/ok (rc 0) cada; AUR-587.sh all → AUR-587/all/pass. Nenhum arquivo de cmd/, internal/ ou pkg/ mudou, então os out/ dos tutoriais continuam válidos e não há dependência Go nova.

Notas

  • A ordem com cards paralelos importa: um card que regrava out/ de tutorial ou muda uma página capturada (por exemplo docs/architecture.md) precisa rodar scripts/docs/capturas.sh e commitar o resultado; senão capturas-check.sh reprova no aceite, no CI e no docs.yml.
  • A busca sem acento acha "deliberacao" pelos caminhos; uma palavra que só aparece acentuada no texto continua exigindo o acento (o lunr não normaliza diacríticos).

Após o merge do AUR-583

O AUR-583 regravou out/ de vários tutoriais (e mudou docs/architecture.md): capturas-check.sh acusou 63 divergências de digest, como previsto. scripts/docs/capturas.sh regenerou as capturas (build sem warning) e o check voltou a ok (229 capturas no manifesto, 183 referencias). Conferência visual de duas capturas mudadas: skills/regra-citavel-terminal.png mostra a linha policy gate: convencoes#logs-sem-dados-pessoais ... depois de app.go:6: [warning] ... e antes de exit_code=3, a nova ordem do log; skills/regra-citavel-comentario.png mostra o último resumo (Changes requested, warning 1, app.go), igual ao log.