Pular para conteúdo

AUR-484: a página inicial ensina a usar, em vez de listar arquivos

Documento histórico do board. Pode descrever componentes removidos; para uso atual, consulte o guia do produto.

Achado

A página publicada em https://mpaape.github.io/AurumCode/ foi lida como visitante novo. O que ela oferecia: três frases sobre as áreas do produto, links para outros documentos, e então ~80% de enumeração crua de páginas geradas (internal/documentation/site/scaffold.go's renderPageBlock, inline no corpo do index.md). Não oferecia nenhum comando copiável, nenhum exemplo de uso, nenhuma indicação de instalação, e nenhuma declaração do que a ferramenta não faz.

O que mudou

internal/documentation/site/scaffold.go ganhou um segundo bloco delimitado, escrito pelo próprio scaffold (determinístico, sem LLM), imediatamente antes do bloco de páginas geradas: <!-- aurumcode:quickstart:start --> / <!-- aurumcode:quickstart:end -->. Esse bloco é sempre reescrito em uma nova execução, exatamente como o bloco de páginas sempre foi — stripGeneratedBlock agora remove a região a partir do primeiro marcador presente (quickstart, com fallback para o marcador antigo em um index.md escrito antes deste card) até o marcador de fim do bloco de páginas.

O conteúdo do bloco é uma constante Go (renderQuickstartBlock), não geração de modelo: existe com ou sem provider de LLM configurado, porque o site publica sem credencial hoje (internal/documentation/welcome continua sendo o caminho opcional de enriquecimento por modelo, e nunca é o único lugar onde este conteúdo aparece).

O que o bloco contém, cada item citando de onde a afirmação sai:

  1. Comando copiável sem credencial — ./aurumcode review --base HEAD~1 --seguranca. Verificado ao vivo neste card (aurumcode review: security pass applied 4 of 8 security rules ..., exit 0) e é a mesma forma usada em docs/getting-started.md e em demo.sh.
  2. Um exemplo por feature: a mesma passagem de segurança para code review; aurumcode docs --source . --output ./site para documentação (forma exata de docs/getting-started.md); e o snippet mínimo de workflow (uses: Mpaape/AurumCode@v1) para páginas — pinado em @v1, nunca @main, coerente com o que AUR-465/AUR-472 exigem.
  3. Limitações declaradas (AC-003):
  4. a passagem de segurança cobre 4 das 8 regras do catálogo: internal/review/rules/security.yml tem 8 regras; apenas 4 carregam pattern hoje (sql-injection, command-injection, hardcoded-secret, xss — confirmado lendo o arquivo diretamente nesta execução). path-traversal, weak-crypto, insecure-random e missing-auth continuam metadado-apenas, citável só por um modelo com provider.
  5. Cobertura por linguagem desigual: .board/cards/ready/AUR-481.md mede que Go, C#, PowerShell, Bash e Rust têm lacunas na regra de command injection (Bash e Rust também na de SQL injection); o exemplo exec.Command(...) do Go e Process.Start(...) do C# não casam com o pattern atual de command-injection, confirmado lendo o próprio regexp em security.yml.
  6. Sem provider de LLM, a review de qualidade não roda — só a passagem determinística executa (mesmo texto de aviso que o binário já imprime).

AC-002: a enumeração deixa de ser o corpo do index

Scaffold.Generate() escreve um segundo arquivo, reference.md, no DocsDir, contendo a listagem completa por linguagem e símbolo (renderPageBlock, inalterado no conteúdo, só realocado) -- mas apenas quando há MAIS DE UMA página gerada (ver decisão de desenho abaixo). index.md recebe renderPageSummaryBlock: para 0 páginas, o texto "No documentation pages were generated"; para 2+, contagem + link [full reference](reference.html); para exatamente 1 página, o link direto para essa página, inline, sem arquivo de referência algum. collectListedPages/collectWalkedPages excluem reference.md da própria varredura, para que uma segunda execução não indexe o arquivo de referência como se fosse uma página gerada.

Decisão de desenho: reference.md não existe para um projeto de 1 página

Medido nesta execução: tests/e2e/browser_chain_test.go e tests/e2e/smoke_test.go andam pelo diretório do site gerado contando páginas de símbolo, e cmd/regenerate-docs/main.go's collectMarkdown (fora de paths/read_paths deste card) faz o mesmo de forma independente para compor a linha aurumcode: result=ok docs=N ... que o CLI imprime de verdade em produção -- ambos excluíam apenas index.md por nome. Um reference.md sempre emitido, mesmo para 1 página, era contado por essas varreduras como uma SEGUNDA página de documentação inventada: o CLI chegou a imprimir docs=2 para um projeto com uma única página real.

Havia duas saídas legítimas: (a) cada varredura passa a excluir reference.md também; (b) o gerador não emite reference.md quando há uma página só. (a) exigiria editar cmd/regenerate-docs/main.go, que este card não pode escrever -- só ler. (b) resolve os três lugares de uma vez, inclusive o que (a) não alcançaria, e é correto por si: uma página de referência cujo único papel é indexar várias páginas por linguagem não tem o que acrescentar quando existe exatamente uma. O custo aceito: a estrutura do site publicado varia com o tamanho do projeto (um projeto de 1 página não tem /reference/; um de 2+ tem). Quem automatiza sobre a estrutura do site precisa checar a existência do arquivo antes de linkar para ele.

Non-goals respeitados

  • O guia completo continua em docs/getting-started.md; o bloco novo é propositalmente curto.
  • Nenhuma prosa gerada por modelo entrou neste bloco.
  • A documentação de API gerada continua acessível (reference.md), só não é mais o corpo da página inicial.
  • Nenhuma limitação foi inventada: as três acima saem de arquivo lido nesta mesma execução (security.yml) ou de medição já registrada (AUR-481).

Fora de escopo deste card

  • internal/pipeline (AUR-483, em paralelo) não foi tocado.
  • .aurumcode/index.md (o arquivo realmente publicado hoje) não está em paths/read_paths deste card e não foi editado à mão; a correção vive no gerador (internal/documentation/site), que o próximo cmd/regenerate-docs volta a escrever por cima da mesma forma.