fix(scripts)!: httpclient 문서 검사가 설정 필드를 절과 표 위치로 대조한다 #88

Merged
donghyeon.kang merged 3 commits from fix/httpclient-docs-field-match into main 2026-11-21 21:12:03 +00:00
Owner

무엇을, 왜

scripts/verify-httpclient-docs.py(release의 httpclient-documentation job)는 manifest(docs/httpclient/env-fields.yaml)의 설정 필드를 마지막 마디로 줄이고(clients[N].tls.enabled → enabled) 아홉 문서를 이은 글에서 부분 문자열로 찾았다. 마지막 마디가 겹치는 이름이 여섯 종(enabled 셋, name, type, protocols, allowed-hosts, allowed-ports)이라 그 이름의 새 필드는 문서 없이 통과했다. 「지운 설정」 표에만 적힌 key도 통과했다. 다섯 종류 추출 어느 것도 0개를 실패로 보지 않았고, transports() 정규식은 숫자를 빼서 HTTP3 꼴 상수를 뽑지 못했다.

이 PR은 설정 필드를 docs/httpclient/configuration-reference.md의 절과 표 첫 칸으로 전체 경로 대조하고, 종류마다 0개면 실패하게 하고, transport 정규식에 숫자를 넣는다. 새 대조로 처음 드러난 최상위 app.httpclient.rotation-drain-timeout 행을 설정 참조에 더했다.

고른 방법과 버린 대안

  • 고른 것: 「절 이름 + leaf」 대조(documented_properties). 머리 첫 칸이 속성인 표만 읽는다. ## 제목의 app.httpclient.<block>이 블록, ### 제목의 코드 표기가 묶음이다. 묶음이 하나면 첫 칸의 bare leaf, 여럿이면 group.leaf를 받는다. 지운 key 표·설명 표(끝낸 것)와 코드 블록 안 표는 세지 않는다. 지금 문서 표 형식을 그대로 읽는다.
  • 버린 것: 마지막 두 마디 대조. 표가 절 아래 leaf만 적어서 51개 필드의 두 마디가 문서에 같이 나오지 않는다. 문서 표 형식부터 바꿔야 했다.
  • 버린 것: 아홉 문서 전체에서 절 구조 찾기. 설정 필드를 찾아볼 곳은 설정 참조 하나다. 다른 문서의 산문 언급은 필드 문서가 아니다.

위험과 영향

  • 파생 서비스: app.httpclient 필드를 더하고 설정 참조의 자기 절 표에 적지 않았으면 release 문서 검사가 새로 실패한다. 그래서 fix(scripts)! + BREAKING CHANGE:이고 docs/upgrade/2026-11-httpclient-docs-check.md에 할 일을 적었다(docs/work/improve.md 7번).
  • 나머지 네 종류(예외·지표·위반 코드·transport)는 전처럼 아홉 문서를 이은 글의 부분 문자열로 찾는다. 이번 카드 범위가 아니다.
  • 실제 트리 대조는 여전히 release job에서만 돈다(시험 모음은 PR의 testDocumentChecks에서 돈다). 이 PR에서는 손으로 돌렸다(아래). 시험은 고정 설정 참조·manifest를 써서, 파생 서비스가 실제 트리에 clients[N].tls.enabled를 더하고 문서화해도 빨개지지 않는다.
  • manifest 형식과 release workflow는 그대로다.

검증

head ea25f624b2fa20a266daa08e92c9eaef4903bd63, 트리 9afb8197f65231b12b86987b4eeedc5f8515a79f, base 0c4c9ed78a2fde04edbeb321b44b386129aac425. push 뒤 origin/main이 6292c52827b50e5516340933fb47d0dd98add4e7(#86, 문서 검사 스크립트)로 나아갔다. 바뀐 파일은 겹치지 않고 git merge-tree --write-tree origin/main HEAD rc=0(합친 트리 aa8f6c9eda01120595647b112724e592b5c3be1f)이다.

무엇 명령 rc 요지
RED(C1) HEAD에 검사기만 0c4c9ed7 판으로 바꾼 트리 d9c5d3381a6438719216901edb07d3dca42724ee에서 (cd scripts/tests && python3 -m unittest test_verify_httpclient_docs) 1 FAIL 4: clients[N].tls.enabled·속성 표 밖 key·빈 manifest·숫자 transport QUIC2가 모두 0 != 1(옛 검사기가 rc=0으로 통과). ERROR 1: documented_properties 없음
GREEN 같은 명령, HEAD 0 8개 OK
변이 검사기에 변이 15개(첫 마디 검사·## 묶음 되돌리기·빈 추출·숫자 정규식·[M] 떼기·첫 칸만·블록 되돌리기·코드 블록·묶음 접두·옛 대조 되살리기·속성 표만·표 사이 머리 되돌리기·여러 묶음 bare·접두 행 등) — 14개를 시험이 잡음. 1개(머리 행도 data로 읽기)는 등가 — 머리 첫 칸이 정확히 속성이면 코드 표기가 없다
C2 실제 트리 python3 -I scripts/verify-httpclient-docs.py(깨끗한 detached worktree) 0 설정 필드 74개 전부 대조, 문서 쪽에만 있는 가짜 경로 0
노트북 docs scripts/verify.sh docs(같은 worktree) 0 scripts 시험 313 OK
desktop pr scripts/verify.sh pr --no-cache --log be-lane-g-12-G3b-pr(같은 worktree) 0 첫 줄 「트리 9afb8197f652(HEAD 트리와 같음)」, 662 executed, tests=7350 failures=0 errors=0 skipped=35, 로그 desktop ~/be-lane-g-12-G3b-pr-logs/pr.log

합친 트리 aa8f6c9e에서는 노트북 scripts/verify.sh docs rc=0(scripts 시험 330 OK)과 C2 rc=0을 봤다. desktop pr은 합친 트리에서 다시 돌리지 않았다(#86은 문서 검사 스크립트만 바꿔 이 PR 파일과 겹치지 않는다).

돌리지 않은 것: release workflow의 httpclient-documentation job 자체(같은 스크립트를 위 C2로 돌렸다). leaf는 바꾸지 않아 leaf 단계는 없다.

리뷰어가 볼 곳

  • 리뷰: 종류 B, 새 눈 1회(렌즈 be-build-ci·be-docs). Low 2(설명 표·지운 key 표의 접두 행을 셈)·Minor 2(시험이 실제 트리에 묶임, 커밋 본문 RED 수)를 이 커밋에 반영했다.

  • scripts/verify-httpclient-docs.py의 documented_properties — 제목·표 읽기 규칙. 지금 설정 참조에서 74개 필드가 모두 맞는지는 실제 트리 실행이 보인다.

  • scripts/tests/test_verify_httpclient_docs.py의 test_the_reference_is_read_by_block_and_group_from_property_tables_only — 규칙 하나마다 fixture 줄 하나.

  • docs/httpclient/configuration-reference.md 「인증서 교체 뒤 비우기」 — HttpClientPlatformSettings.rotationDrainTimeout(기본 30s, 음수면 시작 실패)과 맞는지.

관련

  • 카드 REV-BE-0013(httpclient 문서 검사가 설정 필드를 마지막 마디 낱말 하나로 줄인다)
  • docs/upgrade/2026-11-httpclient-docs-check.md
## 무엇을, 왜 `scripts/verify-httpclient-docs.py`(release의 `httpclient-documentation` job)는 manifest(`docs/httpclient/env-fields.yaml`)의 설정 필드를 마지막 마디로 줄이고(`clients[N].tls.enabled` → `enabled`) 아홉 문서를 이은 글에서 부분 문자열로 찾았다. 마지막 마디가 겹치는 이름이 여섯 종(`enabled` 셋, `name`, `type`, `protocols`, `allowed-hosts`, `allowed-ports`)이라 그 이름의 새 필드는 문서 없이 통과했다. 「지운 설정」 표에만 적힌 key도 통과했다. 다섯 종류 추출 어느 것도 0개를 실패로 보지 않았고, `transports()` 정규식은 숫자를 빼서 `HTTP3` 꼴 상수를 뽑지 못했다. 이 PR은 설정 필드를 `docs/httpclient/configuration-reference.md`의 절과 표 첫 칸으로 전체 경로 대조하고, 종류마다 0개면 실패하게 하고, transport 정규식에 숫자를 넣는다. 새 대조로 처음 드러난 최상위 `app.httpclient.rotation-drain-timeout` 행을 설정 참조에 더했다. ## 고른 방법과 버린 대안 - 고른 것: 「절 이름 + leaf」 대조(`documented_properties`). 머리 첫 칸이 `속성`인 표만 읽는다. `##` 제목의 `app.httpclient.<block>`이 블록, `###` 제목의 코드 표기가 묶음이다. 묶음이 하나면 첫 칸의 bare leaf, 여럿이면 `group.leaf`를 받는다. 지운 key 표·설명 표(`끝낸 것`)와 코드 블록 안 표는 세지 않는다. 지금 문서 표 형식을 그대로 읽는다. - 버린 것: 마지막 두 마디 대조. 표가 절 아래 leaf만 적어서 51개 필드의 두 마디가 문서에 같이 나오지 않는다. 문서 표 형식부터 바꿔야 했다. - 버린 것: 아홉 문서 전체에서 절 구조 찾기. 설정 필드를 찾아볼 곳은 설정 참조 하나다. 다른 문서의 산문 언급은 필드 문서가 아니다. ## 위험과 영향 - 파생 서비스: `app.httpclient` 필드를 더하고 설정 참조의 자기 절 표에 적지 않았으면 release 문서 검사가 새로 실패한다. 그래서 `fix(scripts)!` + `BREAKING CHANGE:`이고 `docs/upgrade/2026-11-httpclient-docs-check.md`에 할 일을 적었다(`docs/work/improve.md` 7번). - 나머지 네 종류(예외·지표·위반 코드·transport)는 전처럼 아홉 문서를 이은 글의 부분 문자열로 찾는다. 이번 카드 범위가 아니다. - 실제 트리 대조는 여전히 release job에서만 돈다(시험 모음은 PR의 `testDocumentChecks`에서 돈다). 이 PR에서는 손으로 돌렸다(아래). 시험은 고정 설정 참조·manifest를 써서, 파생 서비스가 실제 트리에 `clients[N].tls.enabled`를 더하고 문서화해도 빨개지지 않는다. - manifest 형식과 release workflow는 그대로다. ## 검증 head `ea25f624b2fa20a266daa08e92c9eaef4903bd63`, 트리 `9afb8197f65231b12b86987b4eeedc5f8515a79f`, base `0c4c9ed78a2fde04edbeb321b44b386129aac425`. push 뒤 origin/main이 `6292c52827b50e5516340933fb47d0dd98add4e7`(#86, 문서 검사 스크립트)로 나아갔다. 바뀐 파일은 겹치지 않고 `git merge-tree --write-tree origin/main HEAD` rc=0(합친 트리 `aa8f6c9eda01120595647b112724e592b5c3be1f`)이다. | 무엇 | 명령 | rc | 요지 | |---|---|---|---| | RED(C1) | HEAD에 검사기만 `0c4c9ed7` 판으로 바꾼 트리 `d9c5d3381a6438719216901edb07d3dca42724ee`에서 `(cd scripts/tests && python3 -m unittest test_verify_httpclient_docs)` | 1 | FAIL 4: `clients[N].tls.enabled`·속성 표 밖 key·빈 manifest·숫자 transport `QUIC2`가 모두 `0 != 1`(옛 검사기가 rc=0으로 통과). ERROR 1: `documented_properties` 없음 | | GREEN | 같은 명령, HEAD | 0 | 8개 OK | | 변이 | 검사기에 변이 15개(첫 마디 검사·`##` 묶음 되돌리기·빈 추출·숫자 정규식·`[M]` 떼기·첫 칸만·블록 되돌리기·코드 블록·묶음 접두·옛 대조 되살리기·속성 표만·표 사이 머리 되돌리기·여러 묶음 bare·접두 행 등) | — | 14개를 시험이 잡음. 1개(머리 행도 data로 읽기)는 등가 — 머리 첫 칸이 정확히 `속성`이면 코드 표기가 없다 | | C2 실제 트리 | `python3 -I scripts/verify-httpclient-docs.py`(깨끗한 detached worktree) | 0 | 설정 필드 74개 전부 대조, 문서 쪽에만 있는 가짜 경로 0 | | 노트북 docs | `scripts/verify.sh docs`(같은 worktree) | 0 | scripts 시험 313 OK | | desktop pr | `scripts/verify.sh pr --no-cache --log be-lane-g-12-G3b-pr`(같은 worktree) | 0 | 첫 줄 「트리 9afb8197f652(HEAD 트리와 같음)」, 662 executed, tests=7350 failures=0 errors=0 skipped=35, 로그 desktop `~/be-lane-g-12-G3b-pr-logs/pr.log` | 합친 트리 `aa8f6c9e`에서는 노트북 `scripts/verify.sh docs` rc=0(scripts 시험 330 OK)과 C2 rc=0을 봤다. desktop pr은 합친 트리에서 다시 돌리지 않았다(#86은 문서 검사 스크립트만 바꿔 이 PR 파일과 겹치지 않는다). 돌리지 않은 것: release workflow의 `httpclient-documentation` job 자체(같은 스크립트를 위 C2로 돌렸다). leaf는 바꾸지 않아 leaf 단계는 없다. ## 리뷰어가 볼 곳 - 리뷰: 종류 B, 새 눈 1회(렌즈 be-build-ci·be-docs). Low 2(설명 표·지운 key 표의 접두 행을 셈)·Minor 2(시험이 실제 트리에 묶임, 커밋 본문 RED 수)를 이 커밋에 반영했다. - `scripts/verify-httpclient-docs.py`의 `documented_properties` — 제목·표 읽기 규칙. 지금 설정 참조에서 74개 필드가 모두 맞는지는 실제 트리 실행이 보인다. - `scripts/tests/test_verify_httpclient_docs.py`의 `test_the_reference_is_read_by_block_and_group_from_property_tables_only` — 규칙 하나마다 fixture 줄 하나. - `docs/httpclient/configuration-reference.md` 「인증서 교체 뒤 비우기」 — `HttpClientPlatformSettings.rotationDrainTimeout`(기본 30s, 음수면 시작 실패)과 맞는지. ## 관련 - 카드 REV-BE-0013(httpclient 문서 검사가 설정 필드를 마지막 마디 낱말 하나로 줄인다) - `docs/upgrade/2026-11-httpclient-docs-check.md`
donghyeon.kang added 1 commit 2026-11-21 18:27:01 +00:00
verify-httpclient-docs.py는 manifest 필드를 마지막 마디로 줄이고
(clients[N].tls.enabled → enabled) 아홉 문서를 이은 글에서 부분 문자열로
찾는다. 마지막 마디가 겹치는 이름이 여섯 종(enabled 셋, name, type,
protocols, allowed-hosts, allowed-ports)이라 그 이름의 새 필드는 문서 없이
통과한다. 「지운 설정」 표에만 적힌 key도 통과한다. 다섯 종류 추출 어느
것도 0개를 실패로 보지 않고, transport 정규식은 숫자를 빼서 HTTP3 꼴
상수를 뽑지 못한다.

설정 필드는 configuration-reference.md의 속성 표(머리 첫 칸 「속성」)를
제목과 첫 칸으로 읽어(documented_properties) 전체 경로로 대조한다. ##
제목의 app.httpclient.<block>이 블록, ### 제목의 코드 표기가 묶음이다.
지운 key 표·설명 표와 코드 블록 안 표는 세지 않는다. manifest 필드는 끝
[N]·[M]만 뗀다. 종류마다 0개면 실패하고, transport 정규식에 숫자를
넣었다. 이 대조로 처음 드러난 최상위 rotation-drain-timeout 행을 설정
참조에 더했다. 버린 안: 마지막 두 마디 대조. 표가 절 아래 leaf만 적어서
51개 필드의 두 마디가 문서에 같이 나오지 않아, 문서 표 형식부터 바꿔야
했다.

위험: 설정 필드는 이제 configuration-reference.md 속성 표에 있어야 한다.
다른 여덟 문서에만 있으면 실패다. 나머지 네 종류는 전처럼 부분 문자열로
찾는다. 실제 트리 대조는 여전히 release job에서만 돈다. 시험은 고정
설정 참조와 manifest를 써서 실제 트리에 필드를 더해도 빨개지지 않는다.

검증: 새 시험을 main 판 검사기에 얹어 FAIL 4·ERROR 1(새 필드·속성 표
밖 key·빈 manifest·숫자 transport가 rc=0으로 통과, 파서 시험은 함수
없음). 고친 뒤 python3 -m unittest discover -s scripts/tests OK(313),
python3 scripts/verify-httpclient-docs.py rc=0(설정 필드 74, 문서 쪽
남는 경로 0), 검사기 변이 15개 중 14개를 시험이 잡고 1개는 등가,
check-docs.py·check-work-docs.py rc=0.

Refs: REV-BE-0013
BREAKING CHANGE: app.httpclient 필드를 더한 파생 서비스는 그 필드를
  configuration-reference.md의 자기 절 속성 표에 적어야 release 문서
  검사를 통과한다. docs/upgrade/2026-11-httpclient-docs-check.md를 본다.
donghyeon.kang added 1 commit 2026-11-21 18:32:12 +00:00
donghyeon.kang added 1 commit 2026-11-21 19:32:23 +00:00
donghyeon.kang merged commit 43fbec101d into main 2026-11-21 21:12:03 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-backend-template#88