fix(scripts)!: httpclient 문서 검사가 설정 필드를 절과 표 위치로 대조한다 #88
@@ -24,6 +24,15 @@
|
||||
`HTTPCLIENT_ACTIVE_WITHOUT_CLIENTS`로 시작이 실패한다. 부를 대상이 없는 플랫폼도 아무 호출자도 닿을 수 없는
|
||||
transport provider와 gateway를 쥐고 있기 때문이다.
|
||||
|
||||
## 인증서 교체 뒤 비우기
|
||||
|
||||
| 속성 | 타입 | 기본값 | 환경 변수 |
|
||||
|---|---|---|---|
|
||||
| `app.httpclient.rotation-drain-timeout` | duration | `30s` | `APP_HTTPCLIENT_ROTATION_DRAIN_TIMEOUT` |
|
||||
|
||||
인증서를 교체하면 새 런타임 세대가 호출을 받는다. 내린 세대는 이 시간 동안 진행 중인 호출을 마저 끝내고, 시간이
|
||||
지나면 남은 호출이 있어도 pool을 닫는다. 음수면 시작이 실패한다.
|
||||
|
||||
## 환경 변수로 client 선언하기
|
||||
|
||||
client는 이름을 key로 한 map이 아니라, 자기 `name`을 가진 index 목록이다. map key는 환경 변수 이름의 한 조각이
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
# 업그레이드 안내 — 2026-11 HTTP client 문서 검사의 설정 필드 대조
|
||||
|
||||
- 범위: release workflow의 `httpclient-documentation` job이 부르는 `scripts/verify-httpclient-docs.py`. 설정 필드를
|
||||
마지막 마디 낱말이 아니라 설정 참조 문서의 절과 표 위치로 대조하고, 코드에서 뽑은 이름이 0개인 종류를 실패로 본다.
|
||||
운영 코드, 설정 키, manifest 형식은 그대로다.
|
||||
- 근거: 2026-11-22 리뷰 발견 REV-BE-0013. `enabled`·`name`·`type`처럼 흔한 이름의 새 필드가 문서 없이 release를
|
||||
통과했다. 코드의 설정 이름이 문서에 있어야 한다는 것은 이 스크립트가 이미 지키던 규칙이다.
|
||||
|
||||
## 1. 누가 읽나
|
||||
|
||||
이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 HTTP client를 싣고 `app.httpclient` 아래
|
||||
설정 필드를 더했거나 `docs/httpclient/configuration-reference.md`의 절·표를 고친 서비스다.
|
||||
|
||||
## 2. 할 일
|
||||
|
||||
| # | 할 일 | 안 하면 | 해당 서비스 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 더한 설정 필드마다 `docs/httpclient/configuration-reference.md`의 속성 표(머리 첫 칸이 `속성`인 표)에 행을 둔다. 첫 칸에 필드 이름을 코드 표기로 쓰고, 행은 필드가 속한 절 아래에 둔다. `clients[N]` 바로 아래 필드는 `app.httpclient.clients[N]` 절의 표에, 묶음 아래 필드는 그 묶음 이름의 `###` 절(`tls` 아래 `enabled`면 `tls` 절)에 둔다. 절 제목이 묶음 여럿을 이름 대면 첫 칸에 `redirect.enabled`처럼 묶음까지 쓴다. 최상위 필드는 `app.httpclient.<이름>`으로 쓴다 | release의 `httpclient-documentation` job이 `configuration property '<경로>' exists in code but is not documented in a configuration-reference.md table under its section`으로 실패한다. 전에는 필드의 마지막 마디 낱말이 `docs/httpclient`의 아홉 문서 어디에든 있으면 통과했다 | `app.httpclient` 필드를 더한 서비스 |
|
||||
| 2 | 「지운 설정」 표나 설명 표에만 적힌 key를 되살렸으면 그 key를 자기 절의 속성 표로 옮긴다. 머리 첫 칸이 `속성`이 아닌 표(`지운 key`, `끝낸 것`)는 필드를 문서화한 것으로 세지 않는다 | 1번과 같은 실패 | 지운 key를 되살린 서비스 |
|
||||
| 3 | 할 일 없음. 숫자가 든 `TransportType` 상수(`HTTP3` 꼴)도 이제 대조한다. 그런 상수를 더했으면 문서에 이름을 적는다 | `transport '<상수>' exists in code but is not documented`로 실패한다. 전에는 그 상수를 뽑지 못해 대조하지 않았다 | transport를 더한 서비스 |
|
||||
| 4 | 할 일 없음. 다섯 종류(예외·지표·시작 위반 코드·설정 필드·transport) 중 코드에서 뽑은 이름이 0개인 종류가 있으면 실패한다. 출처 파일을 고쳐 쓰다 추출 꼴(두 칸 들여쓴 enum 상수, manifest의 `- field:` 행 등)이 달라졌으면 출처를 맞춘다 | `no <종류> found in the code`로 실패한다. 전에는 아무것도 대조하지 않고 통과했다 | 그 출처 파일을 고쳐 쓴 서비스 |
|
||||
|
||||
## 3. 바뀌지 않은 것
|
||||
|
||||
- 설정 필드를 뺀 네 종류는 전처럼 아홉 문서를 이은 글에서 이름을 찾는다.
|
||||
- manifest(`docs/httpclient/env-fields.yaml`)의 형식과 release workflow의 job은 그대로다.
|
||||
- 검사는 한 방향이다. 문서에 있지만 코드에 없는 이름은 실패가 아니다.
|
||||
@@ -8,6 +8,7 @@ from __future__ import annotations
|
||||
import importlib.util
|
||||
import io
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from contextlib import redirect_stdout
|
||||
from pathlib import Path
|
||||
@@ -19,26 +20,247 @@ sys.modules["verify_httpclient_docs"] = verify_httpclient_docs
|
||||
_spec.loader.exec_module(verify_httpclient_docs)
|
||||
|
||||
|
||||
# A configuration reference shaped like the real one: property tables (header `속성`) under block
|
||||
# and group headings, plus a removed-key table and an explanatory table that name settings without
|
||||
# documenting them. The cases below use it instead of the real reference, so a service that adds and
|
||||
# documents `clients[N].tls.enabled` does not turn them red.
|
||||
REFERENCE = """\
|
||||
## `app.httpclient.clients[N]`
|
||||
|
||||
| 속성 | 타입 | 기본값 | 비고 |
|
||||
|---|---|---|---|
|
||||
| `allowed-hosts` | list | 비어 있음 | |
|
||||
|
||||
### 지운 설정
|
||||
|
||||
| 지운 key | 이유 |
|
||||
|---|---|
|
||||
| `timeout.request-write-idle` | |
|
||||
| `app.httpclient.clients[N].timeout.proxy-connect` | |
|
||||
|
||||
### `circuit-breaker`
|
||||
|
||||
| 끝낸 것 | Breaker | 이유 |
|
||||
|---|---|---|
|
||||
| `total-call` | 실패로 기록한다 | |
|
||||
|
||||
### `redirect`, `request`, `response`
|
||||
|
||||
| 속성 | 기본값 | 뜻 |
|
||||
|---|---|---|
|
||||
| `redirect.enabled` | `false` | |
|
||||
|
||||
### `tls`
|
||||
|
||||
| 속성 | 기본값 | 뜻 |
|
||||
|---|---|---|
|
||||
| `profile-id` | — | |
|
||||
|
||||
### `proxy`와 `observability`
|
||||
|
||||
| 속성 | 기본값 | 뜻 |
|
||||
|---|---|---|
|
||||
| `proxy.enabled` | `false` | |
|
||||
"""
|
||||
|
||||
|
||||
def run_main() -> tuple[int, str]:
|
||||
output = io.StringIO()
|
||||
with redirect_stdout(output):
|
||||
rc = verify_httpclient_docs.main()
|
||||
return rc, output.getvalue()
|
||||
|
||||
|
||||
class HttpclientDocsTest(unittest.TestCase):
|
||||
# No case runs the verifier over the real tree and expects 0: that is the release workflow's
|
||||
# check, and this suite runs in the pull-request gate (documentCheck).
|
||||
|
||||
def setUp(self) -> None:
|
||||
self._workdir = tempfile.TemporaryDirectory()
|
||||
self.workdir = Path(self._workdir.name)
|
||||
self._saved = {
|
||||
name: getattr(verify_httpclient_docs, name)
|
||||
for name in ("ENV_FIELD_MANIFEST", "TRANSPORT_TYPE", "read_docs", "read_configuration_reference")
|
||||
if hasattr(verify_httpclient_docs, name)
|
||||
}
|
||||
|
||||
def tearDown(self) -> None:
|
||||
for name, value in self._saved.items():
|
||||
setattr(verify_httpclient_docs, name, value)
|
||||
self._workdir.cleanup()
|
||||
|
||||
def use_manifest(self, *fields: str) -> None:
|
||||
manifest = self.workdir / "env-fields.yaml"
|
||||
entries = "".join(f" - field: {field}\n env: APP_HTTPCLIENT_TEST_ONLY\n" for field in fields)
|
||||
manifest.write_text("fields:\n" + entries, encoding="utf-8")
|
||||
verify_httpclient_docs.ENV_FIELD_MANIFEST = manifest
|
||||
|
||||
def use_reference(self, text: str) -> None:
|
||||
# The reference also joins the documentation the other kinds are searched in, as the real
|
||||
# one does.
|
||||
read_docs = self._saved["read_docs"]
|
||||
verify_httpclient_docs.read_docs = lambda: read_docs() + "\n" + text
|
||||
verify_httpclient_docs.read_configuration_reference = lambda: text
|
||||
|
||||
def test_a_metric_missing_from_the_documentation_fails_naming_it(self) -> None:
|
||||
# given
|
||||
metric = verify_httpclient_docs.metric_names()[0]
|
||||
original = verify_httpclient_docs.read_docs
|
||||
verify_httpclient_docs.read_docs = lambda: original().replace(metric, "")
|
||||
output = io.StringIO()
|
||||
try:
|
||||
# when
|
||||
with redirect_stdout(output):
|
||||
rc = verify_httpclient_docs.main()
|
||||
finally:
|
||||
verify_httpclient_docs.read_docs = original
|
||||
|
||||
# when
|
||||
rc, output = run_main()
|
||||
|
||||
# then
|
||||
self.assertEqual(rc, 1)
|
||||
self.assertIn(f"metric '{metric}'", output.getvalue())
|
||||
self.assertIn(f"metric '{metric}'", output)
|
||||
|
||||
def test_a_new_field_whose_leaf_is_documented_in_another_section_fails_naming_its_path(self) -> None:
|
||||
# given: `enabled` is documented, but under redirect and proxy, not under tls
|
||||
self.use_reference(REFERENCE)
|
||||
self.use_manifest("clients[N].redirect.enabled", "clients[N].proxy.enabled", "clients[N].tls.enabled")
|
||||
|
||||
# when
|
||||
rc, output = run_main()
|
||||
|
||||
# then
|
||||
self.assertEqual(rc, 1)
|
||||
self.assertIn("configuration property 'clients[N].tls.enabled'", output)
|
||||
self.assertNotIn("'clients[N].redirect.enabled'", output)
|
||||
self.assertNotIn("'clients[N].proxy.enabled'", output)
|
||||
|
||||
def test_a_new_field_documented_under_its_section_is_not_reported(self) -> None:
|
||||
# given
|
||||
row = "| `profile-id` | — | |\n"
|
||||
self.assertIn(row, REFERENCE)
|
||||
self.use_reference(REFERENCE.replace(row, row + "| `enabled` | `true` | |\n"))
|
||||
self.use_manifest("clients[N].redirect.enabled", "clients[N].proxy.enabled", "clients[N].tls.enabled")
|
||||
|
||||
# when
|
||||
_, output = run_main()
|
||||
|
||||
# then
|
||||
self.assertNotIn("configuration property '", output)
|
||||
|
||||
def test_a_field_named_only_outside_a_property_table_fails(self) -> None:
|
||||
# given: the removed-key table and the circuit-breaker table name these, no property table does
|
||||
self.use_reference(REFERENCE)
|
||||
fields = (
|
||||
"clients[N].timeout.request-write-idle",
|
||||
"clients[N].timeout.proxy-connect",
|
||||
"clients[N].circuit-breaker.total-call",
|
||||
)
|
||||
self.use_manifest(*fields)
|
||||
|
||||
# when
|
||||
rc, output = run_main()
|
||||
|
||||
# then
|
||||
self.assertEqual(rc, 1)
|
||||
for field in fields:
|
||||
self.assertIn(f"configuration property '{field}'", output)
|
||||
|
||||
def test_a_list_field_is_matched_by_its_name_without_the_index(self) -> None:
|
||||
# given
|
||||
self.use_reference(REFERENCE)
|
||||
self.use_manifest("clients[N].allowed-hosts[M]")
|
||||
|
||||
# when
|
||||
_, output = run_main()
|
||||
|
||||
# then
|
||||
self.assertNotIn("configuration property '", output)
|
||||
|
||||
def test_the_reference_is_read_by_block_and_group_from_property_tables_only(self) -> None:
|
||||
# given
|
||||
reference = "\n".join(
|
||||
[
|
||||
"# 설정",
|
||||
"## 주 스위치",
|
||||
"| 속성 | 타입 |",
|
||||
"|---|---|",
|
||||
"| `app.httpclient.enabled` | boolean |",
|
||||
"## `app.httpclient.clients[N]`",
|
||||
"| 속성 | 타입 | 비고 |",
|
||||
"|---|---|---|",
|
||||
"| `name` | string | `app.httpclient.in-another-cell` |",
|
||||
"```yaml",
|
||||
"| 속성 | x |",
|
||||
"|---|---|",
|
||||
"| `fenced` | x |",
|
||||
"```",
|
||||
"### `pool`",
|
||||
"| 속성 | 기본값 |",
|
||||
"|---|---|",
|
||||
"| `max-idle-time` | `30s` |",
|
||||
"| `pool.max-life-time` | `5m` |",
|
||||
"",
|
||||
"| 끝낸 것 | 이유 |",
|
||||
"|---|---|",
|
||||
"| `explained` | not a property table |",
|
||||
"### `redirect`, `request`",
|
||||
"| 속성 | 기본값 |",
|
||||
"|---|---|",
|
||||
"| `redirect.enabled` | `false` |",
|
||||
"| `timeout.dns` | not a group this heading names |",
|
||||
"| `bare` | ambiguous under two groups |",
|
||||
"### 지운 설정",
|
||||
"| 지운 key | 이유 |",
|
||||
"|---|---|",
|
||||
"| `app.httpclient.clients[N].timeout.request-write-idle` | removed |",
|
||||
"## 시작 위반 코드",
|
||||
"| 속성 | x |",
|
||||
"|---|---|",
|
||||
"| `top-level` | x |",
|
||||
"## `app.httpclient.dynamic-targets[N]`",
|
||||
"| 속성 | 기본값 |",
|
||||
"|---|---|",
|
||||
"| `name` | — |",
|
||||
]
|
||||
)
|
||||
|
||||
# when
|
||||
documented = verify_httpclient_docs.documented_properties(reference)
|
||||
|
||||
# then
|
||||
self.assertEqual(
|
||||
documented,
|
||||
{
|
||||
"enabled",
|
||||
"clients[N].name",
|
||||
"clients[N].pool.max-idle-time",
|
||||
"clients[N].pool.max-life-time",
|
||||
"clients[N].redirect.enabled",
|
||||
"top-level",
|
||||
"dynamic-targets[N].name",
|
||||
},
|
||||
)
|
||||
|
||||
def test_a_manifest_with_no_field_fails_instead_of_checking_nothing(self) -> None:
|
||||
# given
|
||||
self.use_manifest()
|
||||
|
||||
# when
|
||||
rc, output = run_main()
|
||||
|
||||
# then
|
||||
self.assertEqual(rc, 1)
|
||||
self.assertIn("no configuration property", output)
|
||||
|
||||
def test_a_transport_constant_with_a_digit_is_checked(self) -> None:
|
||||
# given
|
||||
transport_type = self.workdir / "TransportType.java"
|
||||
transport_type.write_text(
|
||||
"package x;\n\npublic enum TransportType {\n APACHE,\n QUIC2\n}\n", encoding="utf-8"
|
||||
)
|
||||
verify_httpclient_docs.TRANSPORT_TYPE = transport_type
|
||||
|
||||
# when
|
||||
rc, output = run_main()
|
||||
|
||||
# then
|
||||
self.assertEqual(rc, 1)
|
||||
self.assertIn("transport 'QUIC2'", output)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
@@ -7,7 +7,10 @@ The design (§33 "Documentation") requires the support matrix, configuration ref
|
||||
guide and runbook to match the code. Review cannot hold that line by itself, so
|
||||
this verifier extracts the names that are part of the public contract -- stable exceptions, metric
|
||||
names, configuration properties, startup violation codes, and transports -- and fails when one
|
||||
exists in code but nowhere in the documentation.
|
||||
exists in code but nowhere in the documentation. A configuration property must appear where a reader
|
||||
would look it up: in a table of the configuration reference, under the section of its block and
|
||||
group (see `documented_properties`). It also fails when a kind yields no name at all, because an
|
||||
extractor that stopped matching its source would otherwise pass by checking nothing.
|
||||
|
||||
It deliberately checks one direction only. A name documented but not yet implemented is a plan; a
|
||||
name implemented but undocumented is a surprise for whoever is on call.
|
||||
@@ -23,6 +26,11 @@ REPO_ROOT = Path(__file__).resolve().parent.parent
|
||||
PLATFORM = REPO_ROOT / "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient"
|
||||
DOCS_DIR = REPO_ROOT / "docs/httpclient"
|
||||
ENV_FIELD_MANIFEST = REPO_ROOT / "docs/httpclient/env-fields.yaml"
|
||||
CONFIGURATION_REFERENCE = DOCS_DIR / "configuration-reference.md"
|
||||
TRANSPORT_TYPE = PLATFORM / "profile/TransportType.java"
|
||||
PROPERTY_PREFIX = "app.httpclient."
|
||||
PROPERTY_TABLE_HEADER = "속성"
|
||||
CODE_SPAN = re.compile(r"`([^`]+)`")
|
||||
|
||||
REQUIRED_DOCS = [
|
||||
"support-matrix.md",
|
||||
@@ -43,6 +51,82 @@ def read_docs() -> str:
|
||||
)
|
||||
|
||||
|
||||
def read_configuration_reference() -> str:
|
||||
return CONFIGURATION_REFERENCE.read_text(encoding="utf-8")
|
||||
|
||||
|
||||
def documented_properties(reference: str) -> set[str]:
|
||||
"""Field paths the configuration reference lists, spelled as the manifest spells them.
|
||||
|
||||
Only property tables count -- those whose header starts with `속성` -- and only the first cell
|
||||
of their rows, read against the headings above the table. The removed-key table (`지운 key`) and
|
||||
explanatory tables (`끝낸 것`) name settings without documenting a field.
|
||||
|
||||
- A `#` or `##` heading naming `app.httpclient.<block>` opens that block (`clients[N]`,
|
||||
`dynamic-targets[N]`); any other one returns to the top level.
|
||||
- A `###` heading names the group its rows belong to. Under `### `pool`` the bare leaf
|
||||
`max-idle-time` means `clients[N].pool.max-idle-time`. Under a heading naming several groups
|
||||
(`### `redirect`, `request`, `response``) a row spells `group.leaf`; a dotted name whose first
|
||||
segment the heading does not name is ignored, and so is any name under a `###` heading that
|
||||
names no group.
|
||||
- Rows directly under the block heading are its own fields. A name spelled
|
||||
`app.httpclient.<path>` is that path in any property table.
|
||||
|
||||
Matching only the last segment anywhere in the documentation let `clients[N].tls.enabled` pass
|
||||
on the strength of `redirect.enabled`; six last segments are already shared, so any new field
|
||||
with one of those names went undocumented without a failure.
|
||||
"""
|
||||
documented: set[str] = set()
|
||||
block = ""
|
||||
groups: list[str] | None = None
|
||||
in_fence = False
|
||||
header: str | None = None # first header cell of the table being read, None outside a table
|
||||
for line in reference.splitlines():
|
||||
if not line.startswith("|"):
|
||||
header = None
|
||||
if line.startswith("```"):
|
||||
in_fence = not in_fence
|
||||
continue
|
||||
if in_fence:
|
||||
continue
|
||||
heading = re.match(r"(#+)\s", line)
|
||||
if heading:
|
||||
names = CODE_SPAN.findall(line)
|
||||
if len(heading.group(1)) <= 2:
|
||||
block = next(
|
||||
(name[len(PROPERTY_PREFIX) :] for name in names if name.startswith(PROPERTY_PREFIX)),
|
||||
"",
|
||||
)
|
||||
groups = None
|
||||
else:
|
||||
groups = names
|
||||
continue
|
||||
if not line.startswith("|"):
|
||||
continue
|
||||
first_cell = line.split("|")[1]
|
||||
if header is None:
|
||||
header = first_cell.strip()
|
||||
continue
|
||||
if header != PROPERTY_TABLE_HEADER:
|
||||
continue
|
||||
for name in CODE_SPAN.findall(first_cell):
|
||||
if name.startswith(PROPERTY_PREFIX):
|
||||
documented.add(name[len(PROPERTY_PREFIX) :])
|
||||
continue
|
||||
if groups is None:
|
||||
path = name
|
||||
elif "." in name:
|
||||
if name.split(".")[0] not in groups:
|
||||
continue
|
||||
path = name
|
||||
elif len(groups) == 1:
|
||||
path = f"{groups[0]}.{name}"
|
||||
else:
|
||||
continue
|
||||
documented.add(f"{block}.{path}" if block else path)
|
||||
return documented
|
||||
|
||||
|
||||
def stable_exceptions() -> list[str]:
|
||||
error_dir = PLATFORM / "api/error"
|
||||
return sorted(
|
||||
@@ -72,7 +156,7 @@ def violation_codes() -> list[str]:
|
||||
|
||||
|
||||
def configuration_properties() -> list[str]:
|
||||
"""Every leaf property under `app.httpclient`, nested and dynamic blocks included.
|
||||
"""Every leaf property under `app.httpclient` as its full path, nested and dynamic blocks included.
|
||||
|
||||
Read from the environment-field manifest rather than from the record source. The manifest is
|
||||
derived from `HttpClientPlatformSettings` and held to it in both directions by
|
||||
@@ -87,16 +171,15 @@ def configuration_properties() -> list[str]:
|
||||
if not stripped.startswith("- field:"):
|
||||
continue
|
||||
path = stripped[len("- field:") :].strip()
|
||||
leaf = path.split(".")[-1]
|
||||
# `clients[N]` and `allowed-hosts[M]` are documented by name, not by position.
|
||||
names.add(re.sub(r"\[[NM]\]$", "", leaf))
|
||||
# A list such as `allowed-hosts[M]` is documented by name, not by position.
|
||||
names.add(re.sub(r"\[[NM]\]$", "", path))
|
||||
return sorted(names)
|
||||
|
||||
|
||||
def transports() -> list[str]:
|
||||
source = (PLATFORM / "profile/TransportType.java").read_text(encoding="utf-8")
|
||||
source = TRANSPORT_TYPE.read_text(encoding="utf-8")
|
||||
body = source[source.index("public enum TransportType") :]
|
||||
return sorted(set(re.findall(r"^\s{2}([A-Z][A-Z_]*),?$", body, flags=re.MULTILINE)))
|
||||
return sorted(set(re.findall(r"^\s{2}([A-Z][A-Z0-9_]*),?$", body, flags=re.MULTILINE)))
|
||||
|
||||
|
||||
def main() -> int:
|
||||
@@ -106,19 +189,30 @@ def main() -> int:
|
||||
return 1
|
||||
|
||||
documentation = read_docs()
|
||||
reference = documented_properties(read_configuration_reference())
|
||||
failures: list[str] = []
|
||||
|
||||
checks = {
|
||||
"stable exception": stable_exceptions(),
|
||||
"metric": metric_names(),
|
||||
"startup violation code": violation_codes(),
|
||||
"configuration property": configuration_properties(),
|
||||
"transport": transports(),
|
||||
# kind -> (names from the code, where they must appear, how to say where). A string is searched
|
||||
# for the name; the configuration reference is a set of exact field paths.
|
||||
checks: dict[str, tuple[list[str], str | set[str], str]] = {
|
||||
"stable exception": (stable_exceptions(), documentation, ""),
|
||||
"metric": (metric_names(), documentation, ""),
|
||||
"startup violation code": (violation_codes(), documentation, ""),
|
||||
"configuration property": (
|
||||
configuration_properties(),
|
||||
reference,
|
||||
f" in a {CONFIGURATION_REFERENCE.name} table under its section",
|
||||
),
|
||||
"transport": (transports(), documentation, ""),
|
||||
}
|
||||
for kind, names in checks.items():
|
||||
for kind, (names, documented, where) in checks.items():
|
||||
if not names:
|
||||
failures.append(
|
||||
f"no {kind} found in the code: its extractor matched nothing, so none would be checked"
|
||||
)
|
||||
for name in names:
|
||||
if name not in documentation:
|
||||
failures.append(f"{kind} '{name}' exists in code but is not documented")
|
||||
if name not in documented:
|
||||
failures.append(f"{kind} '{name}' exists in code but is not documented{where}")
|
||||
|
||||
if failures:
|
||||
print(f"FAIL httpclient documentation drift ({len(failures)} finding(s)):")
|
||||
@@ -126,9 +220,9 @@ def main() -> int:
|
||||
print(" - " + failure)
|
||||
return 1
|
||||
|
||||
total = sum(len(names) for names in checks.values())
|
||||
total = sum(len(names) for names, _, _ in checks.values())
|
||||
print(f"PASS httpclient documentation covers {total} code-derived name(s):")
|
||||
for kind, names in checks.items():
|
||||
for kind, (names, _, _) in checks.items():
|
||||
print(f" {kind}: {len(names)}")
|
||||
return 0
|
||||
|
||||
|
||||
Reference in New Issue
Block a user