fix(generate-docs): detecta arquivo novo, entrega por PR para develop e falha alto [TH-68786] #55

Merged

tarcisio merged 6 commits from fix/TH-68786-generate-docs-entrega-por-pr into develop 2026-10-08 06:45:33 -03:00

Conversation 0 Commits 6 Files changed 7 +862 -37

tmf-ia commented 2026-10-07 22:03:07 -03:00

Owner

Copy link

O que muda (TH-68786)

O reusável generate-docs.yml ficava verde sem entregar (achado do HelpCor, HCOR-67289):

Antes	Agora
git diff --quiet docs/ não via arquivo novo → "Nenhuma mudança" e exit 0	git add -A -- docs/ + git diff --cached --quiet (arquivo novo conta)
git push HEAD:main (main protegida recusaria)	checkout da base_branch (padrão develop), commit do bot na branch fixa chore/auto-gen-docs-<base> (push --force só nela) e PR aberto ou atualizado pela API — scripts/entregar-docs-gerados.sh, no padrão do backmerge.sh. Nunca push na base, nunca merge
OpenAPI com continue-on-error + || echo	falha de geração reprova; openapi: false pula com ::notice::
sem POSTGRES_DOCS_URL → placeholder --dry-run	::notice::schema pulado: POSTGRES_DOCS_URL ausente, sem arquivo
deps do backend com || true	arquivo de deps presente e instalação falhando = vermelho; suporta uv.lock (uv export --frozen)

Token: o mesmo FORGEJO_TOKEN/FORGEJO_USER que os callers já passam. Nenhum segredo novo. O token precisa de escrita no repo (push da branch + abrir PR); sem permissão o job falha com mensagem explícita.

Inputs novos, todos opcionais com padrão: base_branch (develop), openapi_app (app.main:app), openapi (true). backend_path mantido. Nenhum input removido ou tornado obrigatório; sem bloco secrets: (INFRA-64944).

Este PR também traz a main para a develop (merge e89acfb: #53 SBOM e #54 backend_path, que entraram direto na main), senão o release develop→main conflitaria neste mesmo arquivo.

Callers (grep generate-docs.yml@ nas develop/main, todos @main, só secrets:, sem with:)

Produto	Gatilho	Impacto quando este PR chegar à main do ci-shared
TMF/tmf9	push main + dispatch	passa a ler o código da develop e abrir PR para develop
tarcisio/helpcor-admin	push main + dispatch	idem; destrava HCOR-67289 (schema chega por PR, se POSTGRES_DOCS_URL existir)
TMF/tmf-management	schedule diário + dispatch	sem requirements: deps via uv.lock; se o índice privado exigir token, fica vermelho (antes o OpenAPI era pulado em silêncio). Comentário em auto-tag-on-release.yml cita o push em main: fica desatualizado
tarcisio/fina	só dispatch	sem backend/app/main.py (app em backend/main.py): OpenAPI fica vermelho até o caller passar with: openapi_app: main:app
tarcisio/Priceshow	push main + dispatch	sem backend/: já falhava no cd backend antes; segue vermelho até declarar backend_path
tarcisio/DANI	cópia própria (não chama o reusável)	nenhum
TMF/tmf-platform, tarcisio/tennis-tracking, TMF/design-tokens	não chamam	nenhum

Quem dispara no push de main passa a gerar a partir da develop (é nela que o PR cai). O skip-loop ([auto-gen docs] no head commit) segue valendo: o título do PR do bot contém a marca.

Prova (teste com controle) — tests/generate-docs/test_generate_docs.py, 19 testes

• Controle: o passo antigo (texto literal da develop) no repo com docs/db/schema-snapshot.md novo sai 0 com "Nenhuma mudança em docs/" e HEAD intacto; gera placeholder sem POSTGRES_URL; engole o OpenAPI que falha.
• Novo: detecta o arquivo novo, empurra só chore/auto-gen-docs-develop (develop e main do bare intactas), abre PR head→develop; PR já aberto vira existente; 422/403 reprovam; token só no header; sem POSTGRES_URL imprime o notice e não cria arquivo; OpenAPI quebrado reprova.
• Mutação: voltando a detecção do script para git diff --quiet docs/, a suíte cai com 5 falhas + 1 erro.
• Suíte inteira local (unittest discover por pasta de tests/): todas OK.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Jhn1rqHSES3DQEfP6F22V8

## O que muda (TH-68786) O reusável `generate-docs.yml` ficava **verde sem entregar** (achado do HelpCor, HCOR-67289): | Antes | Agora | |---|---| | `git diff --quiet docs/` não via arquivo novo → "Nenhuma mudança" e exit 0 | `git add -A -- docs/` + `git diff --cached --quiet` (arquivo novo conta) | | `git push HEAD:main` (main protegida recusaria) | checkout da `base_branch` (padrão `develop`), commit do bot na branch fixa `chore/auto-gen-docs-<base>` (push --force só nela) e PR aberto **ou atualizado** pela API — `scripts/entregar-docs-gerados.sh`, no padrão do `backmerge.sh`. Nunca push na base, nunca merge | | OpenAPI com `continue-on-error` + `\|\| echo` | falha de geração reprova; `openapi: false` pula com `::notice::` | | sem `POSTGRES_DOCS_URL` → placeholder `--dry-run` | `::notice::schema pulado: POSTGRES_DOCS_URL ausente`, sem arquivo | | deps do backend com `\|\| true` | arquivo de deps presente e instalação falhando = vermelho; suporta `uv.lock` (`uv export --frozen`) | Token: o mesmo `FORGEJO_TOKEN`/`FORGEJO_USER` que os callers já passam. **Nenhum segredo novo.** O token precisa de escrita no repo (push da branch + abrir PR); sem permissão o job falha com mensagem explícita. Inputs novos, todos opcionais com padrão: `base_branch` (`develop`), `openapi_app` (`app.main:app`), `openapi` (`true`). `backend_path` mantido. Nenhum input removido ou tornado obrigatório; sem bloco `secrets:` (INFRA-64944). Este PR também traz a `main` para a `develop` (merge `e89acfb`: #53 SBOM e #54 `backend_path`, que entraram direto na `main`), senão o release develop→main conflitaria neste mesmo arquivo. ## Callers (grep `generate-docs.yml@` nas develop/main, todos `@main`, só `secrets:`, sem `with:`) | Produto | Gatilho | Impacto quando este PR chegar à `main` do ci-shared | |---|---|---| | TMF/tmf9 | push `main` + dispatch | passa a ler o código da `develop` e abrir PR para `develop` | | tarcisio/helpcor-admin | push `main` + dispatch | idem; destrava HCOR-67289 (schema chega por PR, se `POSTGRES_DOCS_URL` existir) | | TMF/tmf-management | schedule diário + dispatch | sem requirements: deps via `uv.lock`; se o índice privado exigir token, **fica vermelho** (antes o OpenAPI era pulado em silêncio). Comentário em `auto-tag-on-release.yml` cita o push em main: fica desatualizado | | tarcisio/fina | só dispatch | **sem `backend/app/main.py`** (app em `backend/main.py`): OpenAPI fica vermelho até o caller passar `with: openapi_app: main:app` | | tarcisio/Priceshow | push `main` + dispatch | **sem `backend/`**: já falhava no `cd backend` antes; segue vermelho até declarar `backend_path` | | tarcisio/DANI | cópia própria (não chama o reusável) | nenhum | | TMF/tmf-platform, tarcisio/tennis-tracking, TMF/design-tokens | não chamam | nenhum | Quem dispara no push de `main` passa a gerar a partir da `develop` (é nela que o PR cai). O skip-loop (`[auto-gen docs]` no head commit) segue valendo: o título do PR do bot contém a marca. ## Prova (teste com controle) — `tests/generate-docs/test_generate_docs.py`, 19 testes - **Controle:** o passo antigo (texto literal da develop) no repo com `docs/db/schema-snapshot.md` novo sai 0 com "Nenhuma mudança em docs/" e HEAD intacto; gera placeholder sem `POSTGRES_URL`; engole o OpenAPI que falha. - **Novo:** detecta o arquivo novo, empurra só `chore/auto-gen-docs-develop` (develop e main do bare intactas), abre PR head→`develop`; PR já aberto vira `existente`; 422/403 reprovam; token só no header; sem `POSTGRES_URL` imprime o notice e não cria arquivo; OpenAPI quebrado reprova. - **Mutação:** voltando a detecção do script para `git diff --quiet docs/`, a suíte cai com 5 falhas + 1 erro. - Suíte inteira local (`unittest discover` por pasta de `tests/`): todas OK. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01Jhn1rqHSES3DQEfP6F22V8

tmf-ia added 6 commits 2026-10-07 22:03:07 -03:00

feat(ci): reusable de SBOM CycloneDX sem docker CLI (INFRA-68625) ... db90d277a4

Substitui as 3 cópias do sbom.yml (DANI, Hub, TMF9), que chamavam o Trivy por
docker run dentro da tmf-ci-node:20, sem docker CLI (DANI run 3445 de 06/10).
O Trivy 0.68.2 vem da camada do binário da tmf-ci-trivy no registry interno,
conferida pelo digest e pelo sha256. Sem origem externa nem docker-in-docker.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Uab9wJsQ19HdJHwYi2uVip

Merge pull request 'feat(ci): reusable de SBOM CycloneDX sem docker CLI (INFRA-68625)' (#53) from feat/INFRA-68625-reusable-sbom into main ... b5f60394b9

Reviewed-on: #53

fix(ci): timeout dos jobs de docs e backend_path no generate-docs (vindos dos ci-templates do TMF/infra) ... 11dee73f75

Comparação dos ci-templates do TMF/infra com os reusáveis daqui (ADR 0018,
item 5): o ci-shared é mais novo em tudo, menos em duas correções que só a
cópia do infra tinha:

- timeout-minutes nos jobs (sync-docs-to-hub: 10; generate-docs: 15);
- generate-docs com o diretório do backend parametrizado (input
  backend_path, default backend), e os scripts chamados por
  $GITHUB_WORKSPACE, que funciona em qualquer profundidade. O caminho fixo
  backend não serve ao TMF9 (backend/python).

Default preserva o comportamento atual dos callers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JMjEgk99UbPAt74dvqGX3q

Merge pull request 'fix(ci): timeout dos jobs de docs e backend_path no generate-docs (o que os ci-templates do infra tinham a mais)' (#54) from fix/INFRA-ci-templates-do-infra into main ... 5dc0e1bc0f

Reviewed-on: #54

merge: main em develop (#53 SBOM e #54 backend_path do generate-docs) antes do conserto [TH-68786] ... e89acfbac6

A main recebeu #53 e #54 direto; sem trazer para cá, o generate-docs.yml
divergiria e o release develop→main teria conflito no mesmo arquivo.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Jhn1rqHSES3DQEfP6F22V8

fix(generate-docs): detecta arquivo novo, entrega por PR para develop e falha alto [TH-68786] ... aa2a2a197f

- mudança em docs/ detectada com git add -A + git diff --cached (arquivo novo conta);
  antes o git diff --quiet não via o artefato novo e o job saía verde sem entregar
- checkout da base_branch (padrão develop), commit na branch do bot
  chore/auto-gen-docs-<base> e PR aberto/atualizado pela API com o FORGEJO_TOKEN
  que o caller já passa (scripts/entregar-docs-gerados.sh); nunca push na main
- OpenAPI sem continue-on-error nem || echo; openapi=false pula com notice;
  openapi_app configurável (padrão app.main:app); deps do backend falham alto
- sem POSTGRES_DOCS_URL o schema é pulado com ::notice::, sem placeholder
- tests/generate-docs com controle: o passo antigo sai 'Nenhuma mudança',
  gera placeholder e engole a falha do OpenAPI; o novo não

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Jhn1rqHSES3DQEfP6F22V8

tarcisio merged commit 4e8a718867 into develop 2026-10-08 06:45:33 -03:00

tarcisio deleted branch fix/TH-68786-generate-docs-entrega-por-pr 2026-10-08 06:45:34 -03:00

tarcisio referenced this pull request from a commit 2026-10-08 06:45:35 -03:00

Merge pull request 'fix(generate-docs): detecta arquivo novo, entrega por PR para develop e falha alto [TH-68786]' (#55) from fix/TH-68786-generate-docs-entrega-por-pr into develop

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

  

seguranca

Segurança/LGPD — merge só com aprovação do operador

No labels

seguranca

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

TMF/ci-shared!55

No description provided.