Files
DongHyeonka a86e00d6e4
pr / done (pull_request) Successful in 3m35s
fix(hooks): N5는 실행되는 낱말만 세고 N6는 merge-base와 비교한다
N5는 명령 안 어디에 있든 `verify.sh <단계>`를 실행으로 셌다. 그래서
`echo scripts/verify.sh pr`, `bash -n scripts/verify.sh pr`도 desktop
실행이 됐다. here-document는 명령 안 아무 낱말이나 bash·sh·zsh면
스크립트로 읽었고(`grep -c bash <<EOF`), `<<\EOF`·`<<'END NOTE'`
구분자는 못 알아 본문을 명령으로 읽었다. `ssh … gradlew`는 옛 검사
그대로 명령 글 전체에서 낱말을 찾아, 커밋 메시지 본문이나 주석의
`ssh desktop ./gradlew`도 셌다. registry에 없는 leaf 대상, 미추적
파일로 보내기를 거절한 실행(rc 5)처럼 Gradle 전에 멈춘 verify.sh도
셌다.

N6는 HEAD와 비교해서, 이 브랜치에서 새로 쓰고 커밋한 기록을 다듬을
때도 「본문을 되돌린다」를 알렸다. 아직 main에 들어가지 않은 글이라
그 알림은 정당한 수정을 되돌리게 만든다.

고친 방법:
- N5: 단순 명령마다 실제로 실행되는 낱말 하나만 본다. 대입과 감싸개
  (timeout·flock·env·nohup 등, 값 받는 옵션과 앞 인자 수를 표로 둠)
  뒤의 낱말, 셸에 준 스크립트 파일이다. 셸은 옵션을 읽어 -c 스크립트,
  stdin 스크립트(-s 또는 인자 없음), 스크립트 파일, -n(실행 안 함)을
  가른다. ssh 원격 명령은 ssh가 보내는 대로 리다이렉션을 뺀 낱말을
  이어 desktop에서 다시 읽는다. gradlew도 같은 길로 desktop 안에서
  돌 때만 센다. leaf 대상은 registry gradle_path와 대조하고, 출력에
  verify.sh의 거절 문구가 있으면 그 명령의 verify.sh는 세지 않는다.
  스크립트 안의 스크립트는 MAX_NESTING단까지만 읽는다(깊은 ssh 중첩이
  RecursionError로 훅을 죽이지 않게).
- here-document 구분자 정규식이 `\WORD`와 따옴표 안 공백을 받는다.
- N6: 기준 커밋을 verify.sh와 같은
  `git merge-base HEAD "${VERIFY_BASE_REF:-origin/main}"`로 하고, 그
  ref가 없으면 HEAD로 돌아간다. 알림 문구는 기준 커밋 이름을 적는다.

버린 대안:
- README의 N5 문구를 verify.sh 경로로 좁히고 옛 gradlew 검사를 둔다
  — 같은 오판이 gradlew 쪽에 남는다.
- 실패한 Bash는 PostToolUse가 안 돈다고 보고 rc 5를 두지 않는다 —
  `| tail`·`; echo rc=$?`로 끝나면 rc가 0이라 돈다.

위험·한계: 여전히 넛지다. 원격 준비 실패(rc 4)는 출력으로 가리지
못해 센다. flock의 `-c` 꼴, 감싸개 표에 없는 감싸개는 실행으로 보지
않아 알림이 한 번 더 나올 수 있다. 「실행 중」 계획서 체크 상자 수정은
기록 규칙상 본문 수정이라 N6가 계속 알린다(이 브랜치에서 새로 쓴
계획서는 이제 조용하다).

검증(노트북, Python·문서만):
- python3 -m unittest discover -s scripts/tests -p test_hooks.py:
  61개 rc=0(1 skip = 실제 포매터 jar).
- RED: 9c0a7cb3d의 hooks.py에 새 상수 셋만 얹고 새 시험을 돌리면
  rc=1, failures=20.
- 변이: 이 커밋이 더하거나 건드린 조건 41개를 하나씩 끈 사본에서
  모두 rc=1(생존 0).
- python3 scripts/check-docs.py, scripts/check-work-docs.py rc=0.
2026-11-22 02:09:28 +09:00

744 lines
43 KiB
Python

"""scripts/hooks/hooks.py의 시험. 고장 낸 입력에서 알림·차단이 나오고, 맞는 입력에서 조용한지 본다.
python3 -m unittest discover -s scripts/tests
"""
from __future__ import annotations
import importlib.util
import io
import json
import os
import re
import stat
import subprocess
import sys
import tempfile
import textwrap
import unittest
from contextlib import redirect_stderr, redirect_stdout
from pathlib import Path
from unittest import mock
SCRIPTS = Path(__file__).resolve().parent.parent
REPO = SCRIPTS.parent
_spec = importlib.util.spec_from_file_location("hooks", SCRIPTS / "hooks/hooks.py")
hooks = importlib.util.module_from_spec(_spec)
sys.modules["hooks"] = hooks
_spec.loader.exec_module(hooks)
REGISTRY = {"modules": [
{"id": "domain-core", "gradle_path": ":domain-core", "source_path": "src/domain/core", "allowed_dependencies": []},
{"id": "shared-contract", "gradle_path": ":shared-contract", "source_path": "src/shared-contract",
"allowed_dependencies": []},
{"id": "application-core", "gradle_path": ":application-core", "source_path": "src/application/core",
"allowed_dependencies": ["domain-core", "shared-contract"]},
{"id": "adapter-inbound-web", "gradle_path": ":adapter:inbound:web", "source_path": "src/adapter/inbound/web",
"allowed_dependencies": ["application-core"]},
{"id": "adapter-outbound-persistence-jpa", "gradle_path": ":adapter:outbound:persistence-jpa",
"source_path": "src/adapter/outbound/persistence-jpa", "allowed_dependencies": ["application-core"]},
]}
PACKAGES = {
"src/domain/core": "dev/caskeleton/domain/order/Order.java",
"src/shared-contract": "dev/caskeleton/shared/error/ApiErrorCode.java",
"src/application/core": "dev/caskeleton/application/order/PlaceOrderUseCase.java",
"src/adapter/inbound/web": "dev/caskeleton/adapter/inbound/web/order/OrderRequest.java",
"src/adapter/outbound/persistence-jpa": "dev/caskeleton/adapter/outbound/persistence/order/OrderEntity.java",
}
class Repository:
"""A throwaway project with a registry, one class per leaf and the migration manifest."""
def __init__(self) -> None:
self._directory = tempfile.TemporaryDirectory()
self.root = Path(self._directory.name).resolve()
self.write(hooks.REGISTRY, json.dumps(REGISTRY))
for leaf, source in PACKAGES.items():
package = Path(source).parent.as_posix().replace("/", ".")
self.write(f"{leaf}/src/main/java/{source}", f"package {package};\n\nclass {Path(source).stem} {{}}\n")
self.write(hooks.MIGRATION_MANIFEST,
"# comment line\n" + "a" * 64 + " jpa/core/V1__initialize_or_adopt.sql\n")
self.write(hooks.CATALOG, 'googleJavaFormat = "1.35.0"\n')
def write(self, path: str, text: str) -> Path:
target = self.root / path
target.parent.mkdir(parents=True, exist_ok=True)
target.write_text(text, encoding="utf-8")
return target
def payload(self, path: str, tool: str = "Edit", **extra) -> dict:
return {"session_id": "s1", "cwd": str(self.root), "tool_name": tool,
"tool_input": {"file_path": str(self.root / path)}, **extra}
def close(self) -> None:
self._directory.cleanup()
def run_event(event: str, payload: dict, environment: dict | None = None) -> tuple[int, str, str]:
out, err = io.StringIO(), io.StringIO()
with mock.patch.dict(os.environ, environment or {}, clear=False), \
mock.patch.object(sys, "stdin", io.StringIO(json.dumps(payload))), redirect_stdout(out), redirect_stderr(err):
os.environ.pop("CLAUDE_PROJECT_DIR", None)
code = hooks.main([event])
return code, out.getvalue(), err.getvalue()
def fake_cache(home: Path, version: str = "1.35.0") -> Path:
"""A Gradle user home whose module cache holds the jars the formatter looks for."""
cache = home / "caches/modules-2/files-2.1"
for group, artifact_version in (("com.google.googlejavaformat/google-java-format", version),
("com.google.guava/guava", "33.6.0-jre"),
("com.google.guava/guava", "33.2.1-android"),
("com.google.guava/failureaccess", "1.0.3")):
artifact = group.rsplit("/", 1)[1]
jar = cache / group / artifact_version / "0123abcd" / f"{artifact}-{artifact_version}.jar"
jar.parent.mkdir(parents=True, exist_ok=True)
jar.write_bytes(b"jar")
return cache
def fake_java(folder: Path, body: str) -> str:
"""A `java` on PATH that records its arguments in args.json, then runs `body` (Python) on the file."""
folder.mkdir(parents=True, exist_ok=True)
script = folder / "java"
script.write_text(textwrap.dedent(f"""\
#!{sys.executable}
import json, sys
from pathlib import Path
Path({str(folder / 'args.json')!r}).write_text(json.dumps(sys.argv[1:]))
target = Path(sys.argv[-1])
{body}
"""), encoding="utf-8")
script.chmod(script.stat().st_mode | stat.S_IXUSR)
return f"{folder}{os.pathsep}{os.environ.get('PATH', '')}"
def load_document_checker():
"""The real scripts/check-docs.py as a module, to hold N6 to the rules the gate uses."""
spec = importlib.util.spec_from_file_location("check_docs", SCRIPTS / "check-docs.py")
module = importlib.util.module_from_spec(spec)
sys.modules["check_docs"] = module
spec.loader.exec_module(module)
return module
def added_context(stdout: str) -> str:
return json.loads(stdout)["hookSpecificOutput"]["additionalContext"] if stdout else ""
class RepositoryTestCase(unittest.TestCase):
def setUp(self) -> None:
self.repo = Repository()
self.addCleanup(self.repo.close)
# The formatter is tested on its own; elsewhere a `java` that changes nothing keeps post-edit quiet.
self.cache = tempfile.TemporaryDirectory()
self.addCleanup(self.cache.cleanup)
home = Path(self.cache.name)
fake_cache(home)
self.environment = {"GRADLE_USER_HOME": str(home), "PATH": fake_java(home / "quiet-java", "pass")}
class MigrationGuardTest(RepositoryTestCase):
"""H13 — PreToolUse blocks an edit of an applied migration, and only that."""
MIGRATION = "src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/jpa/core/V1__initialize_or_adopt.sql"
def test_editing_an_applied_migration_is_blocked_with_the_way_out(self) -> None:
self.repo.write(self.MIGRATION, "create table x();\n")
code, _, err = run_event("pre-edit", self.repo.payload(self.MIGRATION))
self.assertEqual(code, 2)
self.assertIn("[H13 적용된 migration 편집 금지]", err)
self.assertIn("새 버전 파일", err)
def test_a_migration_in_another_leaf_is_found_by_its_manifest_key(self) -> None:
path = "src/adapter/outbound/persistence-fileserver/src/main/resources/db/migration/jpa/core/V1__initialize_or_adopt.sql"
self.assertEqual(run_event("pre-edit", self.repo.payload(path, tool="Write"))[0], 2)
def test_a_new_migration_version_is_allowed(self) -> None:
path = self.MIGRATION.replace("V1__initialize_or_adopt", "V3__add_column")
self.assertEqual(run_event("pre-edit", self.repo.payload(path, tool="Write")), (0, "", ""))
def test_other_files_and_other_tools_are_allowed(self) -> None:
self.assertEqual(run_event("pre-edit", self.repo.payload("docs/x.md"))[0], 0)
self.assertEqual(run_event("pre-edit", self.repo.payload(self.MIGRATION, tool="Read"))[0], 0)
class FormatterTest(RepositoryTestCase):
"""The formatter runs one JVM on one file with the jar Gradle cached; it never downloads one."""
SOURCE = "src/domain/core/src/main/java/dev/caskeleton/domain/order/Order.java"
def fake_cache(self, version: str = "1.35.0") -> Path:
return fake_cache(Path(tempfile.mkdtemp(dir=self.cache.name)), version)
def fake_java(self, body: str) -> dict:
folder = Path(tempfile.mkdtemp(dir=self.cache.name))
self.args_file = folder / "args.json"
return {"PATH": fake_java(folder, body)}
def test_the_classpath_is_the_catalog_version_and_the_newest_jre_guava(self) -> None:
classpath, version = hooks.formatter_classpath(self.repo.root, self.fake_cache())
self.assertEqual(version, "1.35.0")
self.assertEqual([jar.name for jar in classpath],
["google-java-format-1.35.0.jar", "guava-33.6.0-jre.jar", "failureaccess-1.0.3.jar"])
def test_a_cache_without_the_catalog_version_skips_and_says_so(self) -> None:
lines = hooks.format_java(self.repo.root, self.SOURCE, self.fake_cache(version="1.28.0"))
self.assertEqual(len(lines), 1)
self.assertIn("google-java-format 1.35.0 jar가 Gradle 캐시", lines[0])
self.assertIn("받거나 설치하지 않는다", lines[0])
def test_the_formatter_gets_the_spotless_flags_and_the_one_file(self) -> None:
cache = self.fake_cache()
with mock.patch.dict(os.environ, self.fake_java("pass")):
self.assertEqual(hooks.format_java(self.repo.root, self.SOURCE, cache), [])
args = json.loads(self.args_file.read_text())
self.assertEqual(args[-3:], ["--skip-reflowing-long-strings", "--replace", str(self.repo.root / self.SOURCE)])
self.assertIn("com.google.googlejavaformat.java.Main", args)
def test_a_rewritten_file_tells_the_model_to_read_it_again(self) -> None:
cache = self.fake_cache()
with mock.patch.dict(os.environ, self.fake_java("target.write_text(target.read_text() + '\\n')")):
lines = hooks.format_java(self.repo.root, self.SOURCE, cache)
self.assertEqual(len(lines), 1)
self.assertIn("다시 읽는다", lines[0])
def test_a_formatter_error_is_reported_with_its_first_lines(self) -> None:
cache = self.fake_cache()
body = "sys.stderr.write('Order.java:3:1: error: class, interface, enum, or record expected\\n'); sys.exit(1)"
with mock.patch.dict(os.environ, self.fake_java(body)):
lines = hooks.format_java(self.repo.root, self.SOURCE, cache)
self.assertIn("읽지 못했다", lines[0])
self.assertIn("error: class, interface", lines[1])
def test_a_skipped_format_is_said_once_per_session(self) -> None:
environment = {"GRADLE_USER_HOME": str(Path(tempfile.mkdtemp(dir=self.cache.name)))}
first = added_context(run_event("post-edit", self.repo.payload(self.SOURCE), environment)[1])
second = run_event("post-edit", self.repo.payload(self.SOURCE), environment)[1]
self.assertIn("포맷을 건너뛰었다", first)
self.assertEqual(second, "")
def test_build_logic_and_non_java_files_are_not_formatted(self) -> None:
self.assertFalse(hooks.wants_format("build-logic/src/main/java/A.java"))
self.assertFalse(hooks.wants_format("src/app/build/generated/A.java"))
self.assertFalse(hooks.wants_format("docs/a.md"))
self.assertTrue(hooks.wants_format(self.SOURCE))
@unittest.skipUnless(hooks.formatter_classpath(REPO, hooks.gradle_cache())[0], "no google-java-format jar in the Gradle cache")
def test_the_real_formatter_matches_spotless_on_a_badly_indented_file(self) -> None:
# Only on a machine whose Gradle cache holds the catalog version (the owner's laptop).
self.repo.write(self.SOURCE, "package dev.caskeleton.domain.order;\nimport java.util.List;\n"
"class Order{ List<String> lines(){return List.of(\"a\");}}\n")
lines = hooks.format_java(self.repo.root, self.SOURCE, hooks.gradle_cache())
self.assertIn("다시 썼다", lines[0])
self.assertEqual((self.repo.root / self.SOURCE).read_text(), textwrap.dedent("""\
package dev.caskeleton.domain.order;
import java.util.List;
class Order {
List<String> lines() {
return List.of("a");
}
}
"""))
class BoundaryNudgeTest(RepositoryTestCase):
"""N1 — imports of one main source against the registry and the purity lists."""
def nudge(self, leaf: str, relative: str, imports: str) -> str:
package = Path(relative).parent.as_posix().replace("/", ".")
path = f"{leaf}/src/main/java/{relative}"
self.repo.write(path, f"package {package};\n\n{imports}\nclass {Path(relative).stem} {{}}\n")
code, out, _ = run_event("post-edit", self.repo.payload(path), self.environment)
self.assertEqual(code, 0)
return added_context(out)
def test_spring_in_the_domain_is_hard_stop_1(self) -> None:
text = self.nudge("src/domain/core", "dev/caskeleton/domain/order/Line.java",
"import org.springframework.stereotype.Component;")
self.assertIn("HARD-STOP 1 의심: `domain-core`가 `org.springframework.stereotype.Component`", text)
self.assertIn("architectureCheck", text)
def test_an_owned_library_in_the_application_is_flagged(self) -> None:
text = self.nudge("src/application/core", "dev/caskeleton/application/order/Notify.java",
"import dev.cakit.messaging.api.MessageEnvelope;")
self.assertIn("`application-core`가 `dev.cakit.messaging.api.MessageEnvelope`", text)
def test_an_inbound_dto_in_the_application_is_hard_stop_3(self) -> None:
text = self.nudge("src/application/core", "dev/caskeleton/application/order/Place.java",
"import dev.caskeleton.adapter.inbound.web.order.OrderRequest;")
self.assertIn("HARD-STOP 3 의심: `dev.caskeleton.adapter.inbound.web.order.OrderRequest`는 leaf "
"`adapter-inbound-web`의 것인데 `application-core`", text)
def test_a_persistence_entity_in_a_controller_is_hard_stop_2(self) -> None:
text = self.nudge("src/adapter/inbound/web", "dev/caskeleton/adapter/inbound/web/order/OrderController.java",
"import dev.caskeleton.adapter.outbound.persistence.order.OrderEntity;\n"
"import org.springframework.data.repository.CrudRepository;")
self.assertIn("HARD-STOP 2 의심: `dev.caskeleton.adapter.outbound.persistence.order.OrderEntity`", text)
self.assertIn("HARD-STOP 2 의심: `adapter-inbound-web`가 `org.springframework.data.repository.CrudRepository`", text)
def test_a_transitive_registry_edge_nested_and_static_imports_pass(self) -> None:
text = self.nudge("src/adapter/inbound/web", "dev/caskeleton/adapter/inbound/web/order/OrderController.java",
"import dev.caskeleton.application.order.PlaceOrderUseCase;\n"
"import dev.caskeleton.domain.order.Order.Line;\n"
"import static dev.caskeleton.shared.error.ApiErrorCode.of;\n"
"import dev.caskeleton.domain.order.*;\n"
"import org.springframework.web.bind.annotation.RestController;")
self.assertEqual(text, "")
def test_test_sources_and_files_outside_any_leaf_are_not_checked(self) -> None:
path = "src/domain/core/src/test/java/dev/caskeleton/domain/order/OrderTest.java"
self.repo.write(path, "package dev.caskeleton.domain.order;\nimport org.springframework.util.Assert;\nclass OrderTest {}\n")
self.assertEqual(hooks.boundary_findings(self.repo.root, path, (self.repo.root / path).read_text()), [])
self.assertEqual(hooks.boundary_findings(self.repo.root, "src/other/src/main/java/A.java", "import org.springframework.X;"), [])
class DocumentNudgeTest(RepositoryTestCase):
"""N2 — a document edit runs the two document checks and passes on their failure lines."""
def checks(self, work_docs_failures: list[str], docs_failures: list[str]) -> None:
for name, failures in (("check-work-docs.py", work_docs_failures), ("check-docs.py", docs_failures)):
body = "import sys\n" + "".join(f"print({' ' + line!r}, file=sys.stderr)\n" for line in failures)
body += "sys.exit(1)\n" if failures else ""
self.repo.write(f"scripts/{name}", body)
def test_failures_naming_the_edited_document_come_back(self) -> None:
self.checks(["docs/guide.md:3: broken relative link 'x.md'", "docs/other.md:1: history ID"],
["[link] docs/guide.md:3: 없는 곳을 가리키는 상대 링크다: x.md"])
self.repo.write("docs/guide.md", "# 안내\n")
code, out, _ = run_event("post-edit", self.repo.payload("docs/guide.md"), self.environment)
text = added_context(out)
self.assertEqual(code, 0)
self.assertIn("문서 검사 알림(N2) docs/guide.md", text)
self.assertIn("broken relative link 'x.md'", text)
self.assertIn("없는 곳을 가리키는 상대 링크다", text)
self.assertNotIn("docs/other.md", text)
self.assertNotIn("print(", text)
def test_failures_elsewhere_are_shown_when_none_names_the_document(self) -> None:
self.checks(["AGENTS.md: 41 lines, limit 40"], [])
self.repo.write("docs/guide.md", "# 안내\n")
text = added_context(run_event("post-edit", self.repo.payload("docs/guide.md"), self.environment)[1])
self.assertIn("AGENTS.md: 41 lines, limit 40", text)
def test_passing_checks_add_nothing(self) -> None:
self.checks([], [])
self.repo.write("docs/guide.md", "# 안내\n")
self.assertEqual(run_event("post-edit", self.repo.payload("docs/guide.md"), self.environment), (0, "", ""))
class RecordBodyNudgeTest(RepositoryTestCase):
"""N6 — a record keeps the body after its head block as written; docs/vision.md is the owner's."""
DESIGN = "docs/design/2026-11-01-example-design.md"
ADR = "docs/adr/ADR-EX-001-example.md"
REVIEW = "docs/reviews/2026-11-01-example/README.md"
BODY = ["", "# 예시", "", "## 배경", "", "옛 방식을 쓴다.", "", "## 결정", "", "새 방식을 쓴다.", ""]
def setUp(self) -> None:
super().setUp()
# The real checker, so N6 reads the record folders and the head block end the gate uses.
self.repo.write(hooks.DOC_CHECKER, (REPO / hooks.DOC_CHECKER).read_text(encoding="utf-8"))
self.rules = hooks.record_rules(REPO)
# N2 runs the document checks on every document edit and has its own tests.
quiet = mock.patch.object(hooks, "doc_findings", return_value=[])
quiet.start()
self.addCleanup(quiet.stop)
self.repo.write(self.DESIGN, self.record("상태: 채택", self.BODY))
self.repo.write(self.ADR, self.record("상태: 채택", self.BODY))
self.repo.write(self.REVIEW, "# 리뷰\n\n발견 0건.\n")
self.repo.write(hooks.VISION, "# 비전\n\n> 소유자가 직접 쓴다.\n")
for command in (["init", "-q"], ["add", "-A"], ["commit", "-q", "-m", "기록"]):
self.git(*command)
# The base is ${VERIFY_BASE_REF:-origin/main}; the owner's shell may set one.
environment = mock.patch.dict(os.environ)
environment.start()
self.addCleanup(environment.stop)
os.environ.pop(hooks.BASE_REF_VARIABLE, None)
def git(self, *command: str) -> None:
subprocess.run(["git", "-c", "user.name=test", "-c", "user.email=test@example.invalid",
"-c", "core.hooksPath=/dev/null", "-c", "commit.gpgsign=false", *command],
cwd=self.repo.root, check=True, capture_output=True)
def record(self, status: str, body: list[str]) -> str:
head = [self.rules["HEAD_START"], "> **기록**", "", f"- {status}", "- 작성일: 2026-11-01", self.rules["HEAD_END"]]
return "\n".join(head + body)
def edit(self, path: str, text: str) -> tuple[int, str]:
self.repo.write(path, text)
code, out, _ = run_event("post-edit", self.repo.payload(path), self.environment)
return code, added_context(out)
def changed(self, old: str, new: str) -> list[str]:
return [new if line == old else line for line in self.BODY]
def test_the_record_rules_are_the_document_checkers(self) -> None:
self.assertIsNotNone(self.rules, "scripts/check-docs.py에서 N6가 읽는 상수를 찾지 못했다")
checker = load_document_checker()
for path in ("docs/design/a.md", "docs/history/plans/a.md", "docs/adr/a.md", self.REVIEW,
"docs/work/README.md", hooks.VISION):
self.assertEqual(hooks.is_record(self.rules, path), checker.record_kind(path) is not None, path)
for text in (self.record("상태: 채택", self.BODY), "# 머리 블록 없음\n\n본문\n",
"\n".join(["# 시작 줄 없음", self.rules["HEAD_END"], "본문"]),
"\n".join([self.rules["HEAD_START"]] + ["- 칸"] * 30 + [self.rules["HEAD_END"], "본문"])):
body, _ = hooks.record_body(self.rules, text)
expected = checker.strip_head_block(text.split("\n"))
self.assertEqual(body, expected[:len(body)], text[:40])
self.assertFalse("".join(expected[len(body):]).strip(), text[:40])
def test_changing_only_the_head_block_is_quiet(self) -> None:
self.assertEqual(self.edit(self.DESIGN, self.record("상태: 대체됨", self.BODY)), (0, ""))
def test_a_supplement_appended_to_a_decision_record_is_quiet(self) -> None:
supplement = self.BODY[:-1] + ["", "## 보완 (2026-11-22)", "", "보완한 내용이다.", ""]
self.assertEqual(self.edit(self.ADR, self.record("상태: 채택(보완)", supplement)), (0, ""))
def test_a_record_not_committed_yet_is_quiet(self) -> None:
path = "docs/history/plans/2026-11-22-new-plan.md"
self.assertEqual(self.edit(path, self.record("상태: 실행 중", ["", "새 계획이다."])), (0, ""))
def test_a_review_record_is_not_checked_here(self) -> None:
self.assertEqual(self.edit(self.REVIEW, "# 리뷰\n\n발견 1건.\n"), (0, ""))
def test_a_changed_body_line_of_a_design_record_is_named(self) -> None:
code, text = self.edit(self.DESIGN, self.record("상태: 채택", self.changed("옛 방식을 쓴다.", "옛 방식을 고쳐 쓴다.")))
self.assertEqual(code, 0)
self.assertIn(f"기록 본문 알림(N6) {self.DESIGN}:", text)
self.assertIn("머리 블록 칸만 고친다", text)
# No origin/main in this repository: the base is HEAD.
self.assertIn("기준 커밋(HEAD)과 1곳 다르다", text)
self.assertIn("12행: 기준 「옛 방식을 쓴다.」 → 지금 「옛 방식을 고쳐 쓴다.」", text)
def test_a_record_written_and_committed_on_this_branch_is_quiet(self) -> None:
# The base is where this branch left origin/main, before the branch wrote and committed this plan.
self.git("update-ref", "refs/remotes/origin/main", "HEAD")
path = "docs/history/plans/2026-11-22-branch-plan.md"
self.repo.write(path, self.record("상태: 실행 중", ["", "- [ ] 1단계"]))
self.git("add", "-A")
self.git("commit", "-q", "-m", "계획")
self.assertEqual(self.edit(path, self.record("상태: 실행 중", ["", "- [x] 1단계"])), (0, ""))
def test_a_body_change_committed_on_this_branch_is_named_at_the_next_edit(self) -> None:
self.git("branch", "trunk")
changed = self.changed("옛 방식을 쓴다.", "옛 방식을 고쳐 쓴다.")
self.repo.write(self.DESIGN, self.record("상태: 채택", changed))
self.git("commit", "-q", "-am", "본문 고침")
# VERIFY_BASE_REF moves the base, as it does for scripts/verify.sh.
os.environ[hooks.BASE_REF_VARIABLE] = "trunk"
code, text = self.edit(self.DESIGN, self.record("상태: 대체됨", changed))
self.assertEqual(code, 0)
self.assertIn("기준 커밋(merge-base trunk)과 1곳 다르다", text)
self.assertIn("12행: 기준 「옛 방식을 쓴다.」 → 지금 「옛 방식을 고쳐 쓴다.」", text)
def test_the_base_is_the_one_verify_sh_compares_with(self) -> None:
script = (REPO / "scripts/verify.sh").read_text(encoding="utf-8")
self.assertIn(f'git merge-base HEAD "${{{hooks.BASE_REF_VARIABLE}:-{hooks.BASE_REF_DEFAULT}}}"', script)
def test_a_section_appended_to_a_design_record_is_named(self) -> None:
appended = self.BODY[:-1] + ["", "## 덧붙인 절", ""]
self.assertIn("기록 본문 알림(N6)", self.edit(self.DESIGN, self.record("상태: 채택", appended))[1])
def test_a_changed_middle_of_a_decision_record_is_named_even_with_a_supplement(self) -> None:
body = self.changed("옛 방식을 쓴다.", "다른 방식을 쓴다.")[:-1] + ["", "## 보완 (2026-11-22)", ""]
code, text = self.edit(self.ADR, self.record("상태: 채택(보완)", body))
self.assertEqual(code, 0)
self.assertIn(f"기록 본문 알림(N6) {self.ADR}:", text)
self.assertIn("보완 절로 덧붙이고", text)
self.assertEqual([line for line in text.splitlines() if line.startswith("- ")],
["- 12행: 기준 「옛 방식을 쓴다.」 → 지금 「다른 방식을 쓴다.」"])
def test_blank_lines_added_at_the_end_are_quiet(self) -> None:
self.assertEqual(self.edit(self.DESIGN, self.record("상태: 채택", self.BODY + ["", ""])), (0, ""))
def test_an_appended_section_is_shown_by_its_first_written_line(self) -> None:
appended = self.BODY[:-1] + ["", "## 덧붙인 절", ""]
self.assertIn("18행: 기준 「」 → 지금 「## 덧붙인 절」", self.edit(self.DESIGN, self.record("상태: 채택", appended))[1])
def test_many_changes_stay_within_five_lines(self) -> None:
body = ["" if not line else f"{line} 고침" for line in self.BODY]
text = self.edit(self.DESIGN, self.record("상태: 채택", body))[1]
self.assertLessEqual(len(text.splitlines()), hooks.MAX_LINES)
self.assertIn("곳 더", text)
def test_an_edit_of_the_vision_says_it_is_the_owners(self) -> None:
code, text = self.edit(hooks.VISION, "# 비전\n\n1. 에이전트가 채웠다.\n")
self.assertEqual(code, 0)
self.assertIn("(N6) docs/vision.md: 소유자만 쓴다(docs/vision.md:3-4). 되돌리고 제안만 한다.", text)
def test_without_the_document_checker_the_edit_is_not_failed(self) -> None:
(self.repo.root / hooks.DOC_CHECKER).unlink()
changed = self.record("상태: 채택", self.changed("옛 방식을 쓴다.", "옛 방식을 고쳐 쓴다."))
self.assertEqual(self.edit(self.DESIGN, changed), (0, ""))
def test_a_checker_missing_a_constant_or_computing_one_keeps_n6_quiet(self) -> None:
changed = self.record("상태: 채택", self.changed("옛 방식을 쓴다.", "옛 방식을 고쳐 쓴다."))
literals = "".join(f"{name} = {self.rules[name]!r}\n" for name in hooks.DOC_CHECKER_NAMES if name != "HEAD_END")
for checker in (literals, literals + "HEAD_END = make_end()\n"):
with self.subTest(checker=checker[-30:]):
self.repo.write(hooks.DOC_CHECKER, checker)
self.assertEqual(self.edit(self.DESIGN, changed), (0, ""))
def test_next_to_n2_failure_lines_n6_keeps_only_its_first_line(self) -> None:
failures = ["문서 검사 알림(N2) 실패 줄:", "- [head] 머리 블록 둘째 줄", "- [link] 깨진 링크"]
body = ["" if not line else f"{line} 고침" for line in self.BODY]
with mock.patch.object(hooks, "doc_findings", return_value=failures):
text = self.edit(self.DESIGN, self.record("상태: 채택", body))[1]
self.assertEqual(text.splitlines(), [text.splitlines()[0]] + failures)
self.assertIn("기록 본문 알림(N6)", text.splitlines()[0])
class TurnEndNudgeTest(RepositoryTestCase):
"""N5 — Java edited and no desktop Gradle run since: the turn end says so once."""
SOURCE = "src/domain/core/src/main/java/dev/caskeleton/domain/order/Order.java"
def setUp(self) -> None:
super().setUp()
# scripts/verify.sh reads VERIFY_HOST for its default host; the owner's shell may set one.
environment = mock.patch.dict(os.environ)
environment.start()
self.addCleanup(environment.stop)
os.environ.pop("VERIFY_HOST", None)
def edit_java(self) -> None:
run_event("post-edit", self.repo.payload(self.SOURCE), self.environment)
def stop(self, **extra) -> dict | None:
out = run_event("stop", {"session_id": "s1", "cwd": str(self.repo.root), **extra})[1]
return json.loads(out) if out else None
def bash(self, command: str, response: dict | None = None) -> None:
payload = {"session_id": "s1", "cwd": str(self.repo.root), "tool_name": "Bash", "tool_input": {"command": command}}
run_event("post-bash", payload if response is None else {**payload, "tool_response": response})
def test_a_java_edit_blocks_the_turn_end_once_with_the_reason(self) -> None:
self.edit_java()
first = self.stop()
self.assertEqual(first["decision"], "block")
self.assertIn(f"Java 파일 1개를 고쳤고(`{self.SOURCE}`)", first["reason"])
self.assertIn("HARD-STOP 6", first["reason"])
self.assertIsNone(self.stop())
def test_a_desktop_gradle_run_clears_the_pending_edits(self) -> None:
self.edit_java()
self.bash("ssh -o BatchMode=yes desktop 'cd ~/w && flock /tmp/claude-gates/heavy.lock ./gradlew :domain-core:check'")
self.assertIsNone(self.stop())
def test_a_laptop_command_or_another_host_does_not_count(self) -> None:
self.edit_java()
self.bash("git log --oneline -1 && echo gradlew")
self.bash("ssh buildbox ./gradlew check")
self.assertEqual(self.stop()["decision"], "block")
def blocks_after(self, command: str, response: dict | None = None) -> bool:
"""A Java edit, then `command` (with what it printed): does the turn end still block?"""
self.edit_java()
self.bash(command, response)
reply = self.stop()
return reply is not None and reply["decision"] == "block"
def test_a_verify_sh_gradle_stage_on_the_desktop_clears_the_pending_edits(self) -> None:
for command in ("scripts/verify.sh leaf :domain-core",
"ssh desktop 'cd ~/wt && scripts/verify.sh app --on here'",
"cd /home/me/wt && ./scripts/verify.sh pr --no-cache 2>&1 | tail -3; echo rc=$?",
"scripts/verify.sh nightly --on desktop",
"scripts/verify.sh leaf :domain-core && scripts/verify.sh docs --on here",
"ssh -o BatchMode=yes desktop bash -s <<'EOF'\ncd ~/wt && scripts/verify.sh main --on here\nEOF",
"ssh desktop bash -s <<'EOF' && echo done\nscripts/verify.sh pr --on here\nEOF",
"ssh desktop bash -s <<< 'scripts/verify.sh pr --on here'",
"ssh desktop \"bash -lc 'cd ~/wt && scripts/verify.sh pr --on here'\"",
"bash -c 'scripts/verify.sh leaf :domain-core'",
"ssh desktop scripts/verify.sh leaf :domain-core --on here",
"VERIFY_HOST=buildbox scripts/verify.sh docs && scripts/verify.sh pr",
"VERIFY_HOST= scripts/verify.sh pr",
"scripts/verify.sh pr --on here --on desktop",
"scripts/verify.sh pr --log hooks --include-untracked 2>&1 | tee /tmp/pr.log",
"scripts/verify.sh pr \\\n --no-cache",
"echo start # it's a note\nscripts/verify.sh pr"):
with self.subTest(command=command):
self.assertFalse(self.blocks_after(command))
def test_verify_sh_docs_or_a_run_off_the_desktop_still_blocks(self) -> None:
for command in ("scripts/verify.sh docs",
"scripts/verify.sh pr --on here",
"scripts/verify.sh leaf :domain-core --on buildbox",
"VERIFY_HOST=buildbox scripts/verify.sh pr",
"ssh buildbox 'cd ~/wt && scripts/verify.sh pr --on here'",
"ssh desktop 'cd ~/wt && scripts/verify.sh docs'",
"ssh desktop uptime && scripts/verify.sh pr --on here",
"grep -n verify.sh docs/work/README.md",
"ssh desktop uptime\nscripts/verify.sh pr --on here",
"ssh desktop bash -s <<'EOF'\nuptime\nEOF\nscripts/verify.sh pr --on here",
"ssh desktop 'VERIFY_HOST=buildbox scripts/verify.sh pr'",
"export VERIFY_HOST=buildbox; scripts/verify.sh pr",
"scripts/verify.sh pr --on desktop --on here",
"scripts/verify.sh pr :domain-core",
"scripts/verify.sh leaf --no-cache",
"cat scripts/verify.sh",
"# scripts/verify.sh pr",
"echo 'unclosed && scripts/verify.sh pr",
"scripts/verify.sh pr \\\n --on here",
"scripts/verify.sh docs && ssh"):
with self.subTest(command=command):
self.assertTrue(self.blocks_after(command))
def test_a_here_document_written_as_text_is_not_a_run(self) -> None:
for command in ("cat > /tmp/brief.md <<'EOF'\n검증: scripts/verify.sh leaf :domain-core 못 돌림\nEOF",
"git commit -F - <<'EOF'\nfix: scripts/verify.sh pr 결과를 적는다\nEOF",
"cat <<-EOF > notes.md\n\tscripts/verify.sh pr\n\tEOF\nscripts/verify.sh docs"):
with self.subTest(command=command):
self.assertTrue(self.blocks_after(command))
self.assertFalse(self.blocks_after("bash <<'EOF'\nscripts/verify.sh leaf :domain-core\nEOF"))
def test_a_here_document_delimiter_may_be_escaped_quoted_with_spaces_or_tab_indented(self) -> None:
for command in ("cat > /tmp/b.md <<\\EOF\nscripts/verify.sh pr\nEOF",
"cat > /tmp/b.md <<'END NOTE'\nscripts/verify.sh pr\nEND NOTE",
"cat > /tmp/b.md <<\"END NOTE\"\nscripts/verify.sh pr\nEND NOTE"):
with self.subTest(command=command):
self.assertTrue(self.blocks_after(command))
# The run after the body is still read: the body ended at its delimiter line.
self.assertFalse(self.blocks_after("cat <<-EOF > n.md\n\tx\n\tEOF\nscripts/verify.sh pr"))
def test_quotes_and_comments_are_read_as_the_shell_reads_them(self) -> None:
for command in ('echo "a\\" #b"; scripts/verify.sh pr', "echo a#b && scripts/verify.sh pr"):
with self.subTest(command=command):
self.assertFalse(self.blocks_after(command))
self.assertTrue(self.blocks_after('echo "\\"" # ; scripts/verify.sh pr'))
def test_only_the_word_a_command_runs_counts(self) -> None:
for command in ("timeout -k 10 3600 scripts/verify.sh pr",
"env VERIFY_HOST=desktop nohup scripts/verify.sh pr",
"bash -x scripts/verify.sh leaf :domain-core",
"ssh desktop 'cd ~/w && timeout 600 flock -w 600 /tmp/claude-gates/heavy.lock ./gradlew check'",
"ssh desktop bash <<'EOF'\ncd ~/w && sh ./gradlew check\nEOF",
# ssh sends its remote words, not the redirections the laptop shell applies to ssh.
"ssh desktop 'cd ~/wt && scripts/verify.sh pr --on here' > /tmp/pr.log 2>&1",
"bash -o pipefail -c 'scripts/verify.sh pr | tail -3'",
"bash -- scripts/verify.sh pr",
"bash -s x <<'EOF'\nscripts/verify.sh leaf :domain-core\nEOF"):
with self.subTest(command=command):
self.assertFalse(self.blocks_after(command))
for command in ("echo scripts/verify.sh pr",
"bash -n scripts/verify.sh pr",
"printf '%s\\n' scripts/verify.sh leaf :domain-core",
"grep -c bash <<'EOF'\nscripts/verify.sh pr\nEOF",
"cat > /tmp/x/sh <<'EOF'\nscripts/verify.sh pr\nEOF",
"ssh desktop 'grep -n gradlew ~/w/README.md'",
"git commit -F - <<'EOF'\n검증: ssh desktop ./gradlew check 못 돌림\nEOF",
"ssh desktop uptime\n./gradlew check",
"# ssh desktop ./gradlew check\nls",
"./gradlew check",
# A shell given a script file reads the here-document as that script's input.
"bash scripts/notes.sh <<'EOF'\nscripts/verify.sh pr\nEOF",
# A script a laptop shell runs is on the laptop, so `--on here` is the laptop.
"bash -c 'scripts/verify.sh pr --on here'",
"bash <<'EOF'\nscripts/verify.sh pr --on here\nEOF"):
with self.subTest(command=command):
self.assertTrue(self.blocks_after(command))
def test_scripts_nested_past_the_limit_are_not_read_and_do_not_fail_the_hook(self) -> None:
within = "ssh desktop " * hooks.MAX_NESTING + "./gradlew check"
self.assertFalse(self.blocks_after(within))
code, _, _ = run_event("post-bash", {"session_id": "s1", "cwd": str(self.repo.root), "tool_name": "Bash",
"tool_input": {"command": "ssh desktop " * 2000 + "./gradlew check"}})
self.assertEqual(code, 0)
self.assertTrue(self.blocks_after("ssh desktop " * (hooks.MAX_NESTING + 2) + "./gradlew check"))
def test_a_leaf_target_outside_the_registry_stops_before_gradle(self) -> None:
self.assertTrue(self.blocks_after("scripts/verify.sh leaf src/domain/core 2>&1 | tail -5"))
# Without a readable registry the target is not checked (N1 reads it on the Java edit, so break it after).
self.edit_java()
(self.repo.root / hooks.REGISTRY).write_text("{", encoding="utf-8")
self.bash("scripts/verify.sh leaf :elsewhere")
self.assertIsNone(self.stop())
def test_a_run_verify_sh_refused_to_send_does_not_count(self) -> None:
refusal = (REPO / "scripts/verify.sh").read_text(encoding="utf-8")
self.assertIn(f'echo "{hooks.VERIFY_REFUSED}.', refusal)
message = f"{hooks.VERIFY_REFUSED}. 보낼 것이면 git add 하거나 --include-untracked를 주고,\n .codex/\n"
for response in ({"stdout": message, "stderr": ""}, {"stdout": "", "stderr": message}):
with self.subTest(response=response):
self.assertTrue(self.blocks_after("scripts/verify.sh pr 2>&1 | tail -3", response))
# The same run with Gradle output counts; a refusal does not hide a desktop gradlew in the same command.
self.assertFalse(self.blocks_after("scripts/verify.sh pr | tail -3", {"stdout": "BUILD SUCCESSFUL"}))
self.assertFalse(self.blocks_after("scripts/verify.sh pr; ssh desktop 'cd ~/w && ./gradlew check'",
{"stderr": message}))
def test_verify_host_in_the_environment_moves_the_default_host(self) -> None:
os.environ["VERIFY_HOST"] = "buildbox"
self.assertTrue(self.blocks_after("scripts/verify.sh pr"))
self.assertFalse(self.blocks_after("scripts/verify.sh pr --on desktop"))
# The remote shell does not have the laptop's environment.
self.assertFalse(self.blocks_after("ssh desktop 'cd ~/wt && scripts/verify.sh pr'"))
def test_the_options_are_the_ones_verify_sh_reads(self) -> None:
script = (REPO / "scripts/verify.sh").read_text(encoding="utf-8")
body = script[script.index("\nmain() {"):]
options = re.findall(r"^\s*(--[a-z-]+)\)(.*)$", body, re.M)
self.assertEqual(sorted(name for name, rest in options if "shift 2" in rest), sorted(hooks.VERIFY_VALUE_OPTIONS))
self.assertEqual(sorted(name for name, rest in options if "shift 2" not in rest), sorted(hooks.VERIFY_FLAGS))
def test_the_gradle_stages_are_the_ones_verify_sh_runs_with_gradle(self) -> None:
script = (REPO / "scripts/verify.sh").read_text(encoding="utf-8")
heavy = re.search(r"^\s*docs\) run_docs ;;\n\s*([a-z| ]+)\)", script, re.M)
self.assertIsNotNone(heavy, "scripts/verify.sh run_here의 단계 목록을 찾지 못했다")
self.assertEqual(sorted(stage.strip() for stage in heavy.group(1).split("|")),
sorted(hooks.VERIFY_HEAVY_STAGES))
def test_the_reason_points_at_the_verify_entry_point(self) -> None:
self.edit_java()
self.assertIn("`scripts/verify.sh leaf <gradle-path>`", self.stop()["reason"])
def test_a_new_java_edit_after_the_reminder_reminds_again(self) -> None:
self.edit_java()
self.stop()
self.edit_java()
self.assertEqual(self.stop()["decision"], "block")
def test_an_active_stop_hook_never_blocks_again(self) -> None:
self.edit_java()
self.assertIsNone(self.stop(stop_hook_active=True))
def test_no_java_edit_no_reminder(self) -> None:
self.assertIsNone(self.stop())
class SettingsWiringTest(unittest.TestCase):
"""The committed project settings call these hooks on the events they are written for."""
def setUp(self) -> None:
self.settings = json.loads((REPO / ".claude/settings.json").read_text(encoding="utf-8"))
def commands(self, event: str, matcher: str | None) -> list[str]:
groups = [group for group in self.settings["hooks"][event] if group.get("matcher") == matcher]
return [hook["command"] for group in groups for hook in group["hooks"]]
def test_every_event_calls_its_hook(self) -> None:
script = 'python3 "$CLAUDE_PROJECT_DIR"/scripts/hooks/hooks.py'
self.assertEqual(self.commands("PreToolUse", "Edit|Write|MultiEdit"), [f"{script} pre-edit"])
self.assertEqual(self.commands("PostToolUse", "Edit|Write|MultiEdit"), [f"{script} post-edit"])
self.assertEqual(self.commands("PostToolUse", "Bash"), [f"{script} post-bash"])
self.assertEqual(self.commands("Stop", None), [f"{script} stop"])
def test_real_env_files_are_denied_and_the_examples_are_not(self) -> None:
deny = self.settings["permissions"]["deny"]
for name in (".env", ".env.local", ".env.lane"):
self.assertIn(f"Read(**/{name})", deny)
self.assertIn(f"Edit(**/{name})", deny)
self.assertFalse([rule for rule in deny if "example" in rule or rule.endswith(".env.*)")])
def test_the_hook_script_runs_from_the_command_line(self) -> None:
with tempfile.TemporaryDirectory() as project:
result = subprocess.run([sys.executable, str(SCRIPTS / "hooks/hooks.py"), "stop"], input="{}",
capture_output=True, text=True, cwd=project,
env={**os.environ, "CLAUDE_PROJECT_DIR": project})
self.assertEqual((result.returncode, result.stdout), (0, ""))
if __name__ == "__main__":
unittest.main()