feat: a documentação passa a falhar sozinha quando diverge do código - #5
Merged
Merged
Conversation
Documentacao envelhece em silencio. Uma variavel renomeada, uma flag que saiu do CLI, uma rota que mudou de nome -- nada disso quebra teste nem aparece num diff de revisao. Quem descobre e o leitor, quando o comando nao funciona, e ele nao tem como saber que o errado e o texto. tools/valida_docs.py extrai de cada pagina o que e verificavel -- variaveis de ambiente, flags de linha de comando e rotas HTTP -- e confronta com o fonte. tests/test_documentacao_bate_com_codigo.py roda isso no CI. Tres erros reais desta rodada teriam sido pegos por ele: - a pagina de saida de rede do 9RTKSync descrevia o gateway do irmao, com campos que nao existem aqui; - a wiki do OminiRTkSync anunciava uma resposta de /healthz que o servidor nunca devolveu; - o README do LiteLlmRTKSync citava uma rota POST /api/sync inexistente. O verificador distingue o que e nosso do que e de terceiro: uma linha que invoca pip, docker ou tailscale traz as flags DELES, e uma rota citada numa frase sobre o gateway e do gateway. Ruido treina o leitor a ignorar o verificador inteiro, entao ele so acusa o que e realmente nosso. Verificado: os tres repositorios passam, e uma copia com variavel inventada e flag inexistente falha apontando arquivo e linha.
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
![github-code-quality[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
| try: | ||
| with open(os.path.join(pasta, a), encoding="utf-8") as f: | ||
| partes.append(f.read()) | ||
| except (OSError, UnicodeDecodeError): |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentação envelhece em silêncio. Uma variável renomeada, uma flag que saiu do CLI, uma rota que mudou de nome — nada disso quebra teste nem aparece num diff de revisão. Quem descobre é o leitor, quando o comando não funciona, e ele não tem como saber que o errado é o texto.
tools/valida_docs.pyextrai de cada página o que é verificável — variáveis de ambiente, flags de linha de comando e rotas HTTP — e confronta com o fonte.tests/test_documentacao_bate_com_codigo.pyroda isso no CI.Três erros reais desta rodada teriam sido pegos por ele
/healthzque o servidor nunca devolveu;POST /api/syncinexistente.Não acusa o que não é nosso
Uma linha que invoca
pip,dockeroutailscaletraz as flags deles; uma rota citada numa frase sobre o gateway é do gateway. Ruído treina o leitor a ignorar o verificador inteiro, então ele só acusa o que é realmente nosso.Prova
Os três repositórios passam com 0 divergências. Uma cópia descartável com uma variável inventada e uma flag inexistente falha, apontando arquivo e linha.
https://claude.ai/code/session_01Dw2Zc66wvY8QBZJmPBeMsT