fix(scripts): 검사 스크립트와 smoke wrapper의 빈틈을 닫고 자기 시험을 더한다

문제:
- README 「새 서비스로 시작하기」의 이름 바꾸기 명령(`git grep -l ... -- src
  scripts`)이 루트 build.gradle·build-logic의 group, config/spotbugs 목록, registry·
  API surface 스냅숏을 놓쳐, 따라 하면 qualityCheck와 surface 검사가 실패했다.
- check-repo-layout.py의 HISTORY_PREFIXES가 없는 폴더 셋(superpowers, evidence,
  study)을 담고 docs/history·docs/design을 빠뜨렸다. 검사 스크립트 머리말에 누가
  부르는지 없었고, check-repo-layout·check-review-index·verify-httpclient-docs에
  자기 시험이 없었다. check-docs.py docstring은 「검사 여섯」(여덟),
  check-work-docs.py는 lychee를 PR workflow라 했다(main).
- run-compose-runtime-smoke.sh가 lane마다 정적 계약 전체를 다시 돌려 nightly마다
  compose config를 수백 번 렌더링했다. handoff lane의 --force-recreate가 1단계
  재시작 수를 지웠고, ps가 빈 결과면 restarts.txt가 비어 재시작 검사가 통과했다.

고친 것:
- 이름 바꾸기 명령을 그 범위로 넓히고 build-logic 자기 패키지는 그대로 둬도
  된다고 적었다.
- HISTORY_PREFIXES를 지금 기록 폴더 넷으로, 머리말에 부르는 곳, docstring 숫자·
  workflow를 고쳤다. 자기 시험 셋을 더했다(scripts/tests 통과, 옛 목록이면
  HISTORY_PREFIXES 시험이 실패한다).
- smoke는 정적 계약을 실행마다 한 번(두 모드 공통) 돌린다. 재시작 수는
  record_restarts가 단계(phase1, final)를 붙여 쌓고, 살핀 컨테이너가 없거나
  inspect·기록이 실패하면 실패한다(호출이 `|| return 1`이라 함수 안 set -e가
  꺼진다).
- verify-httpclient-docs 자기 시험은 실제 트리 대조(release workflow의 검사)를 하지
  않고 누락 탐지만 본다. scripts/tests는 PR 단계에서 돈다.

Refs: RR9-04-04, RR9-04-17, RR9-04-18, RR9-04-26, RR9-04-27
This commit is contained in:
DongHyeonka
2026-11-13 06:34:33 +09:00
parent cbfa776270
commit d904d680af
10 changed files with 261 additions and 19 deletions
+5 -2
View File
@@ -116,12 +116,15 @@ DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src
이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 이 목록이 템플릿 재사용 체크리스트의 정본이다.
1. `settings.gradle`의 `rootProject.name`을 새 서비스 이름으로 바꾼다.
2. 패키지 루트 `dev.caskeleton`을 서비스 패키지로 바꾼다. Java 소스만이 아니라 `AutoConfiguration.imports`·`spring.factories`·빌드 스크립트·설정 파일·생성 명령 템플릿도 이 이름을 쓴다. 바꿀 파일은 이 명령으로 찾는다.
2. 패키지 루트 `dev.caskeleton`을 서비스 패키지로 바꾼다. Java 소스만이 아니라 `AutoConfiguration.imports`·`spring.factories`·빌드 스크립트·설정 파일·생성 명령 템플릿, SpotBugs 제외 목록(`config/spotbugs/`), 루트 `build.gradle`과 build-logic의 `group`, registry와 공개 API 스냅숏(`docs/registries/`, `docs/architecture/`, `docs/notification/api-surface-snapshot.txt`)도 이 이름을 쓴다. 바꿀 파일은 이 명령으로 찾는다. build-logic 자신의 패키지(`dev.caskeleton.buildlogic`)는 앱 패키지가 아니라 그대로 둬도 된다.
```bash
git grep -l 'dev\.caskeleton' -- src scripts
git grep -l -e 'dev\.caskeleton' -- src scripts config build.gradle docs/registries docs/architecture docs/notification
git grep -l -e '"dev\.caskeleton"' -- build-logic/src/main
```
SpotBugs 목록을 빼먹으면 `qualityCheck`가, 스냅숏을 빼먹으면 각 leaf `check`의 API surface 검사가 실패한다.
3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾼다.
4. 새 업무 기능은 `scripts/new-feature.sh <FeatureName>`으로 만들고 [docs/manual/README.md](docs/manual/README.md) 순서대로 채운다. 모듈 이름과 경계는 그대로 둔다.
5. 쓰는 capability의 `runtimeOnly` 줄만 켠다. 켜지 않은 capability leaf는 산출물에 들어가지 않으니 지우지 않아도 된다.
+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)\""