Pular para conteúdo

AUR-564: tutoriais executáveis de qualquer linguagem, benchmark de recall e operação

O que entrega

  • Três tutoriais em docs/tutorials/ (pt-BR), no padrão do AUR-561, linkados da página inicial (docs/index.md) e do índice docs/tutorials/README.md: qualquer-linguagem.md (5 casos e 1 falha), benchmark.md (4 casos e 1 falha) e operacao.md (6 casos e 1 falha).
  • As demonstrações em demo/tutoriais/{qualquer-linguagem,benchmark,operacao}/ (run.sh com uma fase por caso, expected/, out/ da última execução real). Não houve arquivo novo em _lib/.
  • tests/acceptance/AUR-564.sh: all, AC-001..AC-004, AC-002-MUT-001; seletor desconhecido sai 64.

Decisões

  • qualquer-linguagem roda o produto na imagem (_lib), com --network none, --user do chamador e provedor falso; o contexto estrutural é mostrado pelo prompt capturado (AURUMCODE_PROMPT_CAPTURE), com símbolos de nome único por gramática para provar a contribuição de cada uma.
  • benchmark e operacao não rodam o produto na imagem: o harness (tests/benchmark) e o oci-run são o objeto. Go só pelo go-shared; casos que alteram o corpus ou o repositório trabalham numa cópia em .estado/ (git archive HEAD ou clone local) e devolvem a posse ao usuário com chown dentro do container.
  • Tempos de go test e o caminho do módulo são normalizados no registro (<t>s, <modulo>), assim como os caminhos do worktree e do HOME na operação.
  • O aceite confere comandos e flags: aurumcode contra --help; .board/bin/* contra o disco; go-shared <sub>, flags do oci-run, go test -run X e -update-aur523 contra a fonte.
  • O AC-004 do card: cada script de .board/bin e cada profile do registro são citados em operacao.md (com crase), e o aceite confere com ls e o registro.

Achados sobre o produto (honestidade dos tutoriais)

  1. -update-aur523 sai com exit 1 ao acrescentar o primeiro caso novo, embora regrave manifest e relatório: o teste que confere o corpus roda antes do que o regrava. docs/benchmark.md não menciona isso. O tutorial manda rodar de novo sem a flag. (Fora dos paths do card: não corrigido.)
  2. O benchmark mede encanamento, não modelo: o "modelo" é um provedor falso por rótulo (hit/miss/silent/false_alarm). Com 2 defeitos por linguagem, o IC de Wilson de um recall 1.0 começa em 0.3424.
  3. Contexto estrutural é uma lista plana e ruidosa (List, util, Demo) e o YAML de CI não produz símbolo no exemplo.
  4. Seleção por languages: e apelidos não chegam ao review (AUR-565); só o applyTo de .aurumcode/instructions funciona.
  5. Profile fora do registro: trust-root-docker-v1 tem arquivo de profile e não tem entrada em registry.v1.json; release-build-v1 está em profile-owners.tsv e não existe no registro.
  6. Nem todo lock usa a imagem selada (go-git-offline-v1 usa golang@sha256:...), então o repin da imagem selada não os alcança.
  7. O aviso gate verdict reuse unavailable (AURUMCODE_CACHE_DIR not set) aparece em toda execução com gate sem cache.

O que ficou de fora (marcado nos tutoriais)

Rodada com modelo real; --pr poliglota; go-shared down; rebuild da imagem selada, reescrita dos locks e smoke test do repin; atualização real de scanners e execução de um scanner; exit 69 e 70 do oci-run (o 69 foi provocado à mão, mas não está no registro); integração em main.

Execução real

Execução real de run.sh all dos três tutoriais, nesta ordem, com o out/ versionado (resultados por caso, extraídos das linhas RESULTADO: e exit_code= de cada out/<caso>.log):

qualquer-linguagem

  • qualquer-linguagem/repo-poliglota: exit_codes 0; revisao do repositorio poliglota concluida
  • qualquer-linguagem/arquivo-sem-gramatica: exit_codes 0; arquivo sem gramatica declarado, revisao completa, gate.inconclusive: block nao dispara
  • qualquer-linguagem/binario-e-gerado: exit_codes 0 1; sem gate, exit 0 mas o veredito nao e Approve (arquivos fora do alcance); com gate.inconclusive: block, cobertura parcial reprova
  • qualquer-linguagem/politica-terraform: exit_codes 3; achado citando a regra da skill de seguranca em main.tf bloqueou (gate.fail_on: high)
  • qualquer-linguagem/apelidos-e-instrucoes: exit_codes 0; revisao feita
  • qualquer-linguagem/falha-extensao-desconhecida: exit_codes 3; o achado em script.zzqx (sem gramatica) reprovou: extensao desconhecida nao esconde codigo

benchmark

  • benchmark/rodar-corpus: exit_codes 0 0; o harness reproduziu o relatorio versionado (corpus e politica inalterados); -update-aur523 numa copia gerou relatorio .md e .json identicos aos versionados (byte a byte)
  • benchmark/ler-relatorio: exit_codes -; relatorio lido; recall e precisao sempre com intervalo de Wilson
  • benchmark/adicionar-caso: exit_codes 1 0; o primeiro teste reprova (caso fora do manifest); os testes seguintes gravaram manifest e relatorio; a recusa nomeia o caso: java-cmd esta no disco e nao esta no manifest; sem -update, o teste passa com o corpus, o manifest e o relatorio novos (o caso foi aceito)
  • benchmark/aprovado-com-defeito: exit_codes -; o relatorio expoe o caso aprovado com defeito, com o nome do caso
  • benchmark/falha-caso-sem-manifest: exit_codes 1; caso sem manifest recusado pelo harness (exit_code diferente de 0)

operacao

  • operacao/ambiente-go-shared: exit_codes 0 0 0 0 0; go-shared up e idempotente: o container ja estava no ar (ou foi criado); o container monta o cache de modulos do projeto e o volume de build; o Go roda DENTRO do container (a versao vem da imagem de desenvolvimento); go test roda no container, sobre o worktree montado, sem rede
  • operacao/aceite-selado: exit_codes 0 78 66 64 79; aceite selado do card AUR-523 passou: o programa de aceite saiu 0 dentro do container selado; o registro de execucao do oci-run declara exit_code 0 e observation_trusted false; profile nao registrado: exit 78; card inexistente: exit 66; uso errado (falta --card): exit 64; motor pedido (podman) indisponivel: exit 79 inconclusivo, nunca verde
  • operacao/profiles-e-locks: exit_codes -; todo profile do registry tem lock com o digest declarado
  • operacao/dependencia-e-repin: exit_codes 0; go get acrescentou a dependencia na COPIA (GOSUMDB=off: sem verificacao de sumdb, porque nao ha rede); go.mod e go.sum do repositorio real continuam intactos (so a copia mudou); a parte demonstravel do repin foi executada
  • operacao/scanners-por-digest: exit_codes 0 1; o indice de locks confere os digests dos arquivos de lock; scanners.yml alterado sem atualizar o digest do indice: verify.sh reprova
  • operacao/entrega-e-evidencia: exit_codes 0; o pipeline valida o board inteiro, inclusive que todo done tem validated.json com o commit do card
  • operacao/falha-evidencia-ausente: exit_codes 1; card done sem validated.json: o pipeline reprova

Aceite

Execução real do aceite (go-shared, depois selado com oci-run, exit 0, cerca de 56 s):

AUR-564/AC-001/ok (3 tutoriais, casos de uso e falha, indice e nav)
AUR-564/AC-002/ok (--check dos 3 tutoriais; 146 linhas de saida do texto presentes no out/; execucao real na spec)
AUR-564/AC-003/ok (2 comandos do produto, 3 flags conferidas contra --help; 19 conferencias de scripts do board, go-shared, oci-run e go test)
AUR-564/AC-004/ok (13 blocos identicos aos arquivos da demo; so dominios reservados; sem segredo)
AUR-564/AC-002-MUT-001/ok (sem a linha que prova o caso, --check diverge em todos os casos)
oci-run: "exit_code":0

Também executados: bash tests/acceptance/AUR-560.sh all (host, AUR-560/all/ok) e bash scripts/docs/build.sh (exit 0, strict, 0 warnings, páginas tutorials/qualquer-linguagem/, tutorials/benchmark/, tutorials/operacao/).

Lista compartilhada de domínios

demo/tutoriais/_lib/dominios-permitidos.txt (um host por linha; . na frente = host e subdomínios) é lida pelos quatro aceites (AUR-561.sh, 562.sh, 563.sh, 564.sh), que antes tinham listas próprias e reprovavam o texto uns dos outros. Entram: reservados (example.com/.org/.net, .invalid, .test, localhost, 127.0.0.1), github.com, api.github.com, token.actions.githubusercontent.com, docker.io, ghcr.io e o falso positivo declarado java.io (import Java casa com o padrão de domínio).

Execução real na árvore mergeada com main (go-shared): AUR-561.sh all, AUR-562.sh all, AUR-563.sh all e AUR-564.sh all, todos exit 0. Mutação, numa cópia: acrescentar uma URL de host fora da lista a docs/tutorials/revisao.md derrubou AUR-561.sh AC-004, AUR-562.sh AC-004, AUR-564.sh AC-004 e AUR-563.sh AC-003 (url-real: <host>).

Causa da intermitência (exit 141) e correção

Sob set -o pipefail, consumidores que fecham o pipe cedo (| head -n1 dentro de $(...) e | grep -q .) fazem o grep da esquerda morrer com SIGPIPE (141) quando a saída é maior que o buffer do pipe, de forma intermitente. Nos quatro aceites (AUR-561.sh, 562.sh, 563.sh, 564.sh) head -n1 virou sed -n '1p' (lê tudo) e | grep -q . virou | awk 'END{exit NR==0}'. Nenhum head ou grep -q ao fim de pipe resta.

Prova: all dos quatro aceites, 3 vezes cada, 12 execuções simultâneas pelo go-shared, todas exit 0, nenhum 141. Mutação de domínio numa cópia (host fora da lista em docs/tutorials/gate.md): AUR-562.sh AC-004 e AUR-564.sh AC-004 reprovaram com url-real.