merge: PR #27을 합친 검사 브랜치에 넣는다
pr / done (pull_request) Successful in 12m50s

# Conflicts:
#	src/adapter/inbound/graphql/AGENTS.md
This commit is contained in:
DongHyeonka
2026-11-13 07:30:18 +09:00
70 changed files with 729 additions and 627 deletions
+5 -3
View File
@@ -1,5 +1,7 @@
#!/usr/bin/env python3
"""문서 검사 여섯: 언어, 기록의 머리 블록, 참조, 복사한 숫자, 문서 지도, 루트 README 절. 하나라도 걸리면 rc=1이다.
"""문서 검사 여덟: 언어, 기록의 머리 블록, 참조, 복사한 숫자, 문서 지도, 모듈 README 절, 상대 링크, 문체. 하나라도 걸리면 rc=1이다.
부르는 곳: PR 단계 `prCheck`의 `documentCheck`(루트 `build.gradle`), `scripts/verify.sh docs`.
규칙의 정본은 design-docs `conventions/docs-system.md`이고, 이 repo의 적용은 `docs/README.md`
「문서 수명과 언어」다. 이 스크립트는 그 규칙 중 기계로 볼 수 있는 것만 본다.
@@ -39,8 +41,8 @@
python3 -c 'import hashlib,sys; print(hashlib.sha256(sys.argv[1].encode()).hexdigest()[:16])' "<줄>"
- 2026-11-07 번역 단계에서 목록의 줄을 모두 지워 목록과 FROZEN이 비었다.
python3 scripts/check-docs.py # 여섯 모두
python3 scripts/check-docs.py --only head # 하나만 (language, head, reference, number, map, readme)
python3 scripts/check-docs.py # 여덟 모두
python3 scripts/check-docs.py --only head # 하나만 (CHECKS의 이름 하나)
python3 -m unittest discover -s scripts/tests # 이 검사의 시험
Gradle 밖에 둔다. 빌드는 문서를 파싱하지 않는다(build-logic/AGENTS.md 「저장소 파일을 읽는 테스트」).
+5 -3
View File
@@ -1,6 +1,8 @@
#!/usr/bin/env python3
"""저장소 루트와 src/ 최상위에 허용 목록 밖의 항목이 생기면 실패한다.
부르는 곳: PR 단계 `prCheck`의 `verifyRepositoryLayout`(루트 `build.gradle`), `scripts/verify.sh docs`.
왜: src/ 아래 계층이 아닌 폴더가 2026-07-24의 둘에서 두 달 사이 여덟으로 늘었고, 어느 커밋도 최상위
모양을 묻지 않았다. 루트에는 개발 환경·테스트 fixture·운영 인프라가 섞인 compose 파일과 infra/ 폴더가
쌓였다(2026-11-07 저장소 정리, design-docs repo-structure/01-backend-layout.md). 소유자는 배치 규칙을
@@ -87,11 +89,11 @@ SRC_ALLOWED = {
# 아무도 가리키지 않으면 경고할 파일: 개발 환경과 테스트 fixture.
FIXTURE_SUFFIXES = (".sh", ".acl", ".json", ".yaml", ".yml")
FIXTURE_PREFIXES = ("compose/", "scripts/", "src/bootstrap/app/compose-lanes/")
# 기록 문서 폴더(docs/README.md 「문서 수명과 언어」). 기록이 옛 경로를 적은 것은 참조가 아니다.
HISTORY_PREFIXES = (
"docs/reviews/",
"docs/superpowers/",
"docs/evidence/",
"docs/study/",
"docs/history/",
"docs/design/",
"docs/adr/",
)
+4 -1
View File
@@ -1,6 +1,9 @@
#!/usr/bin/env python3
"""Fail when the work manual stops being readable without history or grows past its size limits.
Called by: the pull-request stage `prCheck` (`verifyWorkDocs`, root `build.gradle`) and
`scripts/verify.sh docs`.
The work manual is the root `AGENTS.md` (the map and the rule book) plus `docs/work/`. A Claude Code
session reads the map through the root `CLAUDE.md`, which imports it (`@AGENTS.md`) and adds a few
Claude-only lines. A session that has never seen this repository's history reads the map,
@@ -28,7 +31,7 @@ This lives outside Gradle on purpose: the build does not parse documents.
python3 scripts/check-work-docs.py --links docs README.md # relative links only, any files
python3 scripts/check-work-docs.py --history docs/manual # history IDs only, any files
The --links form is for machines without lychee (the link checker the pull-request workflow runs).
The --links form is for machines without lychee (the link checker the main-stage workflow runs).
The --history form applies the same history-ID patterns to documents outside docs/work/.
"""
+34 -8
View File
@@ -145,6 +145,25 @@ random_secret() { head -c 32 /dev/urandom | base64 | tr -d '=+/' | cut -c1-32; }
# characters decode to 24 and are rejected. This keeps the padding and the full alphabet.
random_key() { head -c 32 /dev/urandom | base64 | tr -d '\n'; }
# Appends one line per container of the lane's project to restarts.txt, prefixed with the phase.
# Fails when there is no container to inspect: an empty file used to pass the restart check, so a
# lane whose project name drifted reported "no restarts" over containers it never looked at. The
# callers run it as `record_restarts ... || return 1`, which turns `set -e` off inside, so a failed
# inspect returns on its own line instead of counting a container whose line was never written.
record_restarts() {
local phase="$1" container inspected=0
while read -r container; do
[[ -z "${container}" ]] && continue
docker inspect --format "${phase} {{.Name}} restarts={{.RestartCount}} oomKilled={{.State.OOMKilled}}" \
"${container}" >>"${LANE_EVIDENCE}/restarts.txt" || return 1
inspected=$((inspected + 1))
done < <(docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" ps -a -q)
if [[ ${inspected} -eq 0 ]]; then
echo "${id}: no container of project ${PROJECT} to inspect for restarts (${phase})" >&2
return 1
fi
}
run_lane() {
local lane_json="$1"
local id runtime profile
@@ -384,8 +403,8 @@ run_lane() {
echo "== ${id} (project ${PROJECT}, runtime ${runtime})"
# 2. static contract, then render, then create
"${REPO_ROOT}/scripts/verify-compose-profile-contracts.sh" >"${LANE_EVIDENCE}/contract.log" 2>&1
# 2. render, then create. The static contract ran once for the whole run, before the first lane
# (it renders every lane itself, so running it per lane rendered the matrix once per lane).
( cd "${REPO_ROOT}" && docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" config >"${LANE_EVIDENCE}/rendered.yml" )
redact_in_place "${LANE_EVIDENCE}/rendered.yml"
# Build before create. The app service declares both `build:` and `image:`, so Compose reuses a
@@ -528,6 +547,10 @@ run_lane() {
cp "${LANE_EVIDENCE}/health.json" "${LANE_EVIDENCE}/health-phase1.json"
cp "${LANE_EVIDENCE}/info.json" "${LANE_EVIDENCE}/info-phase1.json"
# Recorded before the recreate: --force-recreate makes a new container whose restart count
# starts at zero, so a kill during the first phase would otherwise leave no trace.
record_restarts phase1 || return 1
# The application only. The database and its volume stay up, which is the whole point.
echo "-- ${id}: restarting the application into the second phase"
( cd "${REPO_ROOT}" && docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" stop app >/dev/null 2>&1 )
@@ -595,14 +618,10 @@ run_lane() {
# checks above all ask the application a question, and a restarted application answers them, so
# the restart itself has to be the failure. The peak memory is recorded beside it, so a lane that
# is close to its limit is visible before it crosses it.
local container restarted=""
local restarted=""
docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" exec -T app cat /sys/fs/cgroup/memory.peak \
>"${LANE_EVIDENCE}/app-memory-peak-bytes.txt" 2>/dev/null || true
while read -r container; do
[[ -z "${container}" ]] && continue
docker inspect --format '{{.Name}} restarts={{.RestartCount}} oomKilled={{.State.OOMKilled}}' \
"${container}" >>"${LANE_EVIDENCE}/restarts.txt"
done < <(docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" ps -a -q)
record_restarts final || return 1
restarted="$(grep -v ' restarts=0 oomKilled=false$' "${LANE_EVIDENCE}/restarts.txt" || true)"
if [[ -n "${restarted}" ]]; then
echo "${id}: a container restarted or was killed for memory during the lane:" >&2
@@ -626,6 +645,13 @@ run_lane() {
GENERATED_SECRETS=()
FAILED_LANES=()
# The static contract once for the run, in both modes: it renders every lane by itself, so running it
# inside each lane rendered the whole matrix once per lane.
mkdir -p "${EVIDENCE_ROOT}"
CONTRACT_LOG="${EVIDENCE_ROOT}/contract-${RUN_ID}.log"
"${REPO_ROOT}/scripts/verify-compose-profile-contracts.sh" >"${CONTRACT_LOG}" 2>&1 \
|| { echo "run-compose-runtime-smoke: the static Compose contract failed; see ${CONTRACT_LOG}" >&2; exit 1; }
if [[ "${MODE}" == "lane" ]]; then
lane_json="$(jq -c --arg id "${SELECTED_LANE}" '.lanes[] | select(.id == $id)' "${CONTRACTS}")"
[[ -n "${lane_json}" ]] || { echo "no lane '${SELECTED_LANE}' in ${CONTRACTS}" >&2; exit 64; }
+84
View File
@@ -0,0 +1,84 @@
"""scripts/check-repo-layout.py의 시험. 허용 목록 밖의 항목과 registry 경로를 실패로 보는지 본다.
python3 -m unittest discover -s scripts/tests
"""
from __future__ import annotations
import importlib.util
import json
import sys
import tempfile
import unittest
from pathlib import Path
SCRIPTS = Path(__file__).resolve().parent.parent
_spec = importlib.util.spec_from_file_location("check_repo_layout", SCRIPTS / "check-repo-layout.py")
check_repo_layout = importlib.util.module_from_spec(_spec)
sys.modules["check_repo_layout"] = check_repo_layout
_spec.loader.exec_module(check_repo_layout)
class TopLevelTest(unittest.TestCase):
def test_a_root_entry_outside_the_allow_list_is_not_allowed(self) -> None:
# given
paths = ["AGENTS.md", "stray-notes.txt", "src/domain/core/build.gradle"]
# when
unknown = check_repo_layout.top_level(paths, "") - check_repo_layout.ROOT_ALLOWED.keys()
# then
self.assertEqual(unknown, {"stray-notes.txt"})
def test_a_folder_under_src_that_is_not_a_layer_is_not_allowed(self) -> None:
# given
paths = ["src/domain/core/build.gradle", "src/tools/helper.py"]
# when
unknown = check_repo_layout.top_level(paths, "src/") - check_repo_layout.SRC_ALLOWED.keys()
# then
self.assertEqual(unknown, {"tools"})
class RegistryTest(unittest.TestCase):
def test_a_registry_source_path_outside_the_layer_folders_is_reported(self) -> None:
# given
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
(root / "gradle").mkdir()
modules = [
{"id": "domain-core", "source_path": "src/domain/core"},
{"id": "stray", "source_path": "tools/stray"},
]
(root / check_repo_layout.REGISTRY).write_text(
json.dumps({"modules": modules}), encoding="utf-8"
)
original = check_repo_layout.REPO_ROOT
check_repo_layout.REPO_ROOT = root
try:
# when
problems = check_repo_layout.registry_violations()
finally:
check_repo_layout.REPO_ROOT = original
# then
self.assertEqual(len(problems), 1)
self.assertIn("stray", problems[0])
class HistoryPrefixesTest(unittest.TestCase):
def test_every_history_prefix_is_a_folder_that_exists(self) -> None:
# when
missing = [
prefix
for prefix in check_repo_layout.HISTORY_PREFIXES
if not (check_repo_layout.REPO_ROOT / prefix).is_dir()
]
# then
self.assertEqual(missing, [], "a prefix for a folder that is gone excludes nothing")
if __name__ == "__main__":
unittest.main()
+75
View File
@@ -0,0 +1,75 @@
"""scripts/check-review-index.py의 시험. 영역 문서의 발견이 README 색인에 빠지면 실패하는지 본다.
python3 -m unittest discover -s scripts/tests
"""
from __future__ import annotations
import importlib.util
import io
import sys
import tempfile
import unittest
from contextlib import redirect_stderr, redirect_stdout
from pathlib import Path
SCRIPTS = Path(__file__).resolve().parent.parent
_spec = importlib.util.spec_from_file_location("check_review_index", SCRIPTS / "check-review-index.py")
check_review_index = importlib.util.module_from_spec(_spec)
sys.modules["check_review_index"] = check_review_index
_spec.loader.exec_module(check_review_index)
def run(review: Path) -> int:
argv = sys.argv
sys.argv = ["check-review-index.py", str(review)]
try:
with redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()):
return check_review_index.main()
finally:
sys.argv = argv
class ReviewIndexTest(unittest.TestCase):
def setUp(self) -> None:
self._directory = tempfile.TemporaryDirectory()
self.review = Path(self._directory.name)
(self.review / "01-area.md").write_text(
"# 영역\n\n### RR9-01-01 · Medium · 하나\n\n### RR9-01-02 · Low · 둘\n", encoding="utf-8"
)
def tearDown(self) -> None:
self._directory.cleanup()
def test_a_finding_missing_from_the_index_fails(self) -> None:
# given
(self.review / "README.md").write_text("| RR9-01-01 | Medium |\n", encoding="utf-8")
# when
rc = run(self.review)
# then
self.assertEqual(rc, 1)
def test_an_index_that_names_every_finding_passes(self) -> None:
# given
(self.review / "README.md").write_text(
"| RR9-01-01 | Medium |\n| RR9-01-02 | Low |\n", encoding="utf-8"
)
# when
rc = run(self.review)
# then
self.assertEqual(rc, 0)
def test_a_range_in_the_index_counts_for_every_id_inside_it(self) -> None:
# when
ids = check_review_index.indexed_ids("RR9-01-01~03, RR9-02-05·07")
# then
self.assertEqual(ids, {"RR9-01-01", "RR9-01-02", "RR9-01-03", "RR9-02-05", "RR9-02-07"})
if __name__ == "__main__":
unittest.main()
@@ -0,0 +1,45 @@
"""scripts/verify-httpclient-docs.py의 시험. 코드의 이름이 문서에서 빠지면 실패하는지 본다.
python3 -m unittest discover -s scripts/tests
"""
from __future__ import annotations
import importlib.util
import io
import sys
import unittest
from contextlib import redirect_stdout
from pathlib import Path
SCRIPTS = Path(__file__).resolve().parent.parent
_spec = importlib.util.spec_from_file_location("verify_httpclient_docs", SCRIPTS / "verify-httpclient-docs.py")
verify_httpclient_docs = importlib.util.module_from_spec(_spec)
sys.modules["verify_httpclient_docs"] = verify_httpclient_docs
_spec.loader.exec_module(verify_httpclient_docs)
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 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
# then
self.assertEqual(rc, 1)
self.assertIn(f"metric '{metric}'", output.getvalue())
if __name__ == "__main__":
unittest.main()
+2
View File
@@ -1,6 +1,8 @@
#!/usr/bin/env python3
"""Fail when the HTTP Client Platform's code and documentation have drifted.
Called by: the release workflow (`.gitea/workflows/release.yml`, job `httpclient-documentation`).
The design (§33 "Documentation") requires the support matrix, configuration reference, security
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
+2 -2
View File
@@ -127,7 +127,7 @@ echo ""
echo "=== [architecture] repository-wide verification"
if (cd "${GRADLE_DIR}" \
&& "${GRADLE[@]}" verifyCleanArchitectureDependencies \
&& "${GRADLE[@]}" :app-bootstrap:test --tests '*CleanArchitectureTest'); then
&& "${GRADLE[@]}" :app-bootstrap:architectureTest); then
RAN+=("architecture:repository-wide")
else
FAILED+=("architecture:repository-wide")
@@ -153,7 +153,7 @@ mkdir -p "${MANIFEST_DIR}"
echo "{"
echo " \"commit\": \"$(git -C "${REPO_ROOT}" rev-parse HEAD)\","
echo " \"commitDirty\": $( [[ -n "$(git -C "${REPO_ROOT}" status --porcelain)" ]] && echo true || echo false ),"
echo " \"serverImage\": \"${MONGODB_IMAGE:-mongo:8.0.16}\","
echo " \"serverImage\": \"$(sed -n 's/^mongo-8=//p' "${REPO_ROOT}/gradle/container-images.properties")\","
echo " \"generatedAt\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\","
echo " \"contractManifest\": \"src/adapter/outbound/persistence-mongo/release/release-contracts.json\","
echo " \"contractManifestSha256\": \"$(sha256sum "${REPO_ROOT}/src/adapter/outbound/persistence-mongo/release/release-contracts.json" | cut -d' ' -f1)\""