Files
clean-architecture-frontend…/scripts/tests/test_hooks.py
DongHyeonka f117a5af41 docs(src): 계층 폴더마다 지역 규칙 AGENTS.md를 두고 CLAUDE.md가 가져온다
계층별 규칙이 Claude만 읽는 .claude/rules/에만 있어 다른 에이전트에는
보이지 않았다. 하네스 자료의 3단계는 레이어마다 그 폴더에 AGENTS.md다.

src/의 9개 계층 폴더마다 AGENTS.md(16~20줄)를 둔다: 그 폴더가 하는 일,
그 폴더에만 걸리는 import 금지(.dependency-cruiser.json에서 from이 그
폴더에 맞는 규칙을 뽑아 이름과 함께), 검사하는 게이트, 테스트 위치. 모든
폴더에 걸리는 규칙은 루트 AGENTS.md와 layers.md를 가리킨다. 옆에
@AGENTS.md 한 줄 CLAUDE.md를 둬 Claude Code가 그 폴더 파일을 열 때 같은
책을 읽는다(백엔드와 같은 짝).

- .claude/rules/adapters·features는 폴더 AGENTS.md를 가리키게 줄였다.
- scripts/check-work-docs.py: src/**/AGENTS.md도 이력 ID 0·200줄·짝·링크를
  본다. 훅 N5는 이 파일들을 노트북 확인 파일로 친다.
- docs/reviews/adapters/INVENTORY.md: check:adapter-inventory가 src/adapters
  아래 추적 파일을 모두 요구하므로 두 행(142·143)을 더했다.
- 루트 AGENTS.md 지도가 가장 가까운 src/<계층>/AGENTS.md와 비전·문제 정의
  양식을 가리킨다.

버린 대안: .claude/rules/만 두기(다른 에이전트가 못 읽는다), 폴더 CLAUDE.md
없이 AGENTS.md만(Claude Code는 같은 폴더에 CLAUDE.md가 없고 Read로 열 때만
읽어 백엔드와 갈린다).

위험·한계: 규칙 이름은 지금 규칙 파일에서 뽑았다. 규칙을 더하거나 바꾸면
이 문서도 손으로 고쳐야 한다(정본은 규칙 파일과 check:architecture).

검증: scripts/verify.sh docs rc=0(src/**/AGENTS.md 9개, 최대 20/200),
python3 -m unittest discover -s scripts/tests 62건 통과.
2026-11-08 22:57:03 +09:00

308 lines
15 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 shutil
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)
GIT_ENV = {"GIT_AUTHOR_NAME": "t", "GIT_AUTHOR_EMAIL": "t@example.com", "GIT_COMMITTER_NAME": "t",
"GIT_COMMITTER_EMAIL": "t@example.com", "GIT_CONFIG_COUNT": "1", "GIT_CONFIG_KEY_0": "core.hooksPath",
"GIT_CONFIG_VALUE_0": "/dev/null"}
FILES = {
"src/adapters/http/index.ts": "export * from './client.ts';\n",
"src/adapters/http/client.ts": "export const client = 1;\n",
"src/adapters/auth/index.ts": "export const auth = 1;\n",
"src/adapters/auth/session.ts": "export const session = 1;\n",
"src/adapters/platform/locks.ts": "export const locks = 1;\n",
"src/bootstrap/compose.ts": "export {};\n",
"src/presentation/pages/home-page.tsx": "export {};\n",
"src/domain/order.ts": "export {};\n",
}
class Repository:
"""A throwaway git checkout with the real import rules and a few adapter groups."""
def __init__(self) -> None:
self._directory = tempfile.TemporaryDirectory()
self.root = Path(self._directory.name).resolve()
shutil.copy(REPO / hooks.RULES, self.root / hooks.RULES)
for path, text in FILES.items():
self.write(path, text)
self.git("init", "-q")
self.git("add", "-A")
self.git("commit", "-q", "-m", "base")
def git(self, *args: str) -> None:
subprocess.run(["git", *args], cwd=self.root, check=True, capture_output=True, env={**os.environ, **GIT_ENV})
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) -> tuple[int, str, str]:
out, err = io.StringIO(), io.StringIO()
with mock.patch.dict(os.environ, {}, 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 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)
def edit(self, path: str, text: str) -> str:
self.repo.write(path, text)
code, out, _ = run_event("post-edit", self.repo.payload(path))
self.assertEqual(code, 0)
return added_context(out)
class BoundaryNudgeTest(RepositoryTestCase):
def test_a_deep_import_past_the_barrel_is_item_1(self) -> None:
text = self.edit("src/bootstrap/compose.ts", 'import { client } from "../adapters/http/client.ts";\n')
self.assertIn("경계 알림(N3) src/bootstrap/compose.ts", text)
self.assertIn("꼭 지킬 것 1 의심: `adapter-groups-are-reached-through-their-barrel`", text)
self.assertIn("src/adapters/http/client.ts", text)
def test_the_barrel_is_quiet(self) -> None:
self.assertEqual(self.edit("src/bootstrap/compose.ts", 'import { client } from "../adapters/http/index.ts";\n'), "")
def test_another_adapter_is_item_2_and_the_kernel_is_allowed(self) -> None:
text = self.edit("src/adapters/http/client.ts", textwrap.dedent("""\
import { session } from "../auth/session.ts";
import { locks } from "../platform/locks.ts";
"""))
self.assertIn("꼭 지킬 것 2 의심: `adapters-do-not-know-other-concrete-adapters`", text)
self.assertNotIn("platform/locks", text)
def test_a_package_import_is_checked_by_its_name(self) -> None:
text = self.edit("src/domain/order.ts", 'import { useState } from "react";\n')
self.assertIn("꼭 지킬 것 3 의심: `domain-is-framework-neutral` — `react`", text)
def test_type_only_reexports_and_dynamic_imports_count(self) -> None:
for source in ('export type { Client } from "../../adapters/http/client.ts";\n',
'const page = () => import("../../adapters/http/client.ts");\n',
'import type {\n Client,\n} from "../../adapters/http/client";\n'):
with self.subTest(source=source):
self.assertIn("presentation-does-not-know-adapters",
self.edit("src/presentation/pages/home-page.tsx", source))
def test_findings_are_capped_and_keep_the_gate_line(self) -> None:
text = self.edit("src/presentation/pages/home-page.tsx",
'import { client } from "../../adapters/http/client.ts";\nimport z from "zod";\n')
lines = text.splitlines()
self.assertLessEqual(len(lines), hooks.MAX_LINES)
self.assertRegex(lines[-2], r"^- 외 \d+개$")
self.assertIn("FE-GATE-010", lines[-1])
def test_files_outside_src_and_declarations_are_not_checked(self) -> None:
self.assertEqual(self.edit("tests/unit/x.test.ts", 'import { c } from "../../src/adapters/http/client.ts";\n'), "")
self.assertEqual(self.edit("src/bootstrap/env.d.ts", 'import { c } from "../adapters/http/client.ts";\n'), "")
def test_the_real_rules_find_nothing_in_the_real_sources(self) -> None:
# A nudge the gate would not raise is noise. The repository passes check:architecture, so every
# source file here must be quiet; a new false positive fails this test before it reaches a session.
noisy = []
for path in sorted((REPO / "src").rglob("*")):
if path.suffix in (".ts", ".tsx") and path.is_file():
relative = path.relative_to(REPO).as_posix()
if hooks.boundary_findings(REPO, relative, path.read_text(encoding="utf-8")):
noisy.append(relative)
self.assertEqual(noisy, [])
class StandardNudgeTest(RepositoryTestCase):
TEST = "tests/unit/orders.test.ts"
def setUp(self) -> None:
super().setUp()
self.repo.write(self.TEST, 'it.skip("a", () => {});\nit("b", () => {});\n')
self.repo.git("add", "-A")
self.repo.git("commit", "-q", "-m", "test")
def test_skips_and_only_added_since_the_last_commit_are_reported(self) -> None:
text = self.edit(self.TEST, 'it.skip("a", () => {});\nit.skip("b", () => {});\ndescribe.only("c", () => {});\n')
self.assertIn("게이트 기준 알림(N6) tests/unit/orders.test.ts", text)
self.assertIn("`.only` 0→1", text)
self.assertIn("`.skip` 1→2", text)
self.assertIn("꼭 지킬 것 4", text)
def test_an_unchanged_or_smaller_count_is_quiet(self) -> None:
self.assertEqual(self.edit(self.TEST, 'it.skip("a", () => { expect(1).toBe(1); });\n'), "")
self.assertEqual(self.edit(self.TEST, 'it("a", () => {});\n'), "")
def test_a_new_test_file_counts_from_zero_and_playwright_fixme_counts(self) -> None:
text = self.edit("tests/e2e/new.spec.ts", 'test.fixme("x", async () => {});\n')
self.assertIn("`.fixme` 0→1", text)
def test_a_gate_standard_file_edit_is_reported(self) -> None:
for path in ("config/performance/budgets.json", "config/ci/ungated-tests.json",
"config/scale/feature-shape-ceilings.json", "vitest.config.ts",
"tests/unit/__snapshots__/x.test.ts.snap"):
with self.subTest(path=path):
self.assertIn("게이트의 기준 파일", self.edit(path, "{}\n"))
def test_source_text_that_looks_like_a_skip_is_not_counted(self) -> None:
self.assertEqual(self.edit("src/domain/order.ts", 'export const note = "use it.only when";\n'), "")
class DocumentNudgeTest(RepositoryTestCase):
def checker(self, code: int, stderr_lines: list[str]) -> None:
body = "import sys\n" + "".join(f"print({line!r}, file=sys.stderr)\n" for line in stderr_lines)
self.repo.write(hooks.DOC_CHECK[0], body + f"sys.exit({code})\n")
def test_failures_naming_the_edited_document_come_back_first(self) -> None:
self.checker(1, ["", "FAILED: 2 problem(s)", " docs/work/improve.md:3: history ID '1103/11-07'",
" docs/work/README.md:9: broken relative link 'x.md'"])
text = self.edit("docs/work/improve.md", "# x\n")
self.assertIn("문서 검사 알림(N2) docs/work/improve.md", text)
self.assertIn("1103/11-07", text)
self.assertNotIn("broken relative link", text)
def test_failures_elsewhere_are_shown_when_none_names_the_document(self) -> None:
self.checker(1, [" AGENTS.md: 41 lines, limit 40"])
self.assertIn("AGENTS.md: 41 lines", self.edit("docs/manual/README.md", "# x\n"))
def test_a_passing_check_adds_nothing(self) -> None:
self.checker(0, [])
self.assertEqual(self.edit("docs/work/improve.md", "# x\n"), "")
class TurnEndNudgeTest(RepositoryTestCase):
def stop(self, **extra) -> dict | None:
_, out, _ = run_event("stop", {"session_id": "s1", "cwd": str(self.repo.root), **extra})
return json.loads(out) if out else None
def bash(self, command: str) -> None:
run_event("post-bash", {"session_id": "s1", "cwd": str(self.repo.root), "tool_name": "Bash",
"tool_input": {"command": command}})
def test_an_edit_blocks_the_turn_end_once_with_the_reason(self) -> None:
self.edit("src/domain/order.ts", "export const a = 1;\n")
first = self.stop()
self.assertEqual(first["decision"], "block")
self.assertIn("src/domain/order.ts", first["reason"])
self.assertIn("scripts/verify.sh", first["reason"])
self.assertIsNone(self.stop())
def test_a_desktop_run_clears_the_pending_edits(self) -> None:
for command in ("ssh desktop 'cd ~/workspace/x && corepack pnpm -s lint'",
"scripts/verify.sh merge --log fe-x",
"./scripts/verify.sh gate FE-GATE-005",
"cd /w && scripts/verify.sh script verify:documentation 2>&1 | tail"):
with self.subTest(command=command):
self.edit("src/domain/order.ts", "export const a = 2;\n")
self.bash(command)
self.assertIsNone(self.stop())
def test_laptop_commands_and_other_hosts_do_not_count(self) -> None:
for command in ("corepack pnpm lint", "ssh build-box 'corepack pnpm lint'", "scripts/verify.sh docs",
"scripts/verify.sh hooks", "scripts/verify.sh gate FE-GATE-005 --on here",
"ssh desktop uptime"):
with self.subTest(command=command):
self.edit("src/domain/order.ts", "export const a = 3;\n")
self.bash(command)
self.assertIsNotNone(self.stop())
def test_files_the_laptop_checks_do_not_need_the_desktop(self) -> None:
for path in (".claude/rules/x.md", "scripts/hooks/hooks.py", "scripts/tests/test_x.py", "CLAUDE.md",
"docs/ledger/estimates.jsonl", "scripts/check-work-docs.py", "src/adapters/AGENTS.md",
"src/features/CLAUDE.md"):
self.repo.write(path, "x\n")
run_event("post-edit", self.repo.payload(path))
self.assertIsNone(self.stop())
def test_a_new_edit_after_the_reminder_reminds_again(self) -> None:
self.edit("src/domain/order.ts", "export const a = 4;\n")
self.stop()
self.edit("docs/work/README.md", "# x\n")
self.assertIsNotNone(self.stop())
def test_an_active_stop_hook_never_blocks_again(self) -> None:
self.edit("src/domain/order.ts", "export const a = 5;\n")
self.assertIsNone(self.stop(stop_hook_active=True))
class SettingsWiringTest(unittest.TestCase):
SETTINGS = REPO / ".claude/settings.json"
def setUp(self) -> None:
self.settings = json.loads(self.SETTINGS.read_text(encoding="utf-8"))
def commands(self, event: str, matcher: str | None) -> list[str]:
return [hook["command"] for entry in self.settings["hooks"].get(event, [])
if entry.get("matcher") == matcher for hook in entry["hooks"]]
def test_every_event_calls_its_hook(self) -> None:
self.assertEqual(self.commands("PostToolUse", "Edit|Write|MultiEdit"),
['python3 "$CLAUDE_PROJECT_DIR"/scripts/hooks/hooks.py post-edit'])
self.assertEqual(self.commands("PostToolUse", "Bash"),
['python3 "$CLAUDE_PROJECT_DIR"/scripts/hooks/hooks.py post-bash'])
self.assertEqual(self.commands("Stop", None), ['python3 "$CLAUDE_PROJECT_DIR"/scripts/hooks/hooks.py stop'])
self.assertNotIn("PreToolUse", self.settings["hooks"])
def test_real_env_files_are_denied_and_the_example_is_not(self) -> None:
deny = self.settings["permissions"]["deny"]
for tool in ("Read", "Edit"):
self.assertIn(f"{tool}(**/.env)", deny)
self.assertIn(f"{tool}(**/.env.local)", deny)
self.assertFalse([rule for rule in deny if "example" in rule or rule in ("Read(**/.env.*)", "Edit(**/.env.*)")])
def test_the_harness_plugin_is_enabled_from_its_marketplace(self) -> None:
self.assertEqual(self.settings["enabledPlugins"], {"harness@claude-harness": True})
source = self.settings["extraKnownMarketplaces"]["claude-harness"]["source"]
self.assertEqual(source, {"source": "git",
"url": "https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git"})
def test_the_hook_script_runs_from_the_command_line(self) -> None:
for event in hooks.EVENTS:
result = subprocess.run([sys.executable, str(SCRIPTS / "hooks/hooks.py"), event], input="{}",
capture_output=True, text=True, timeout=10, cwd=tempfile.gettempdir())
self.assertEqual(result.returncode, 0, event + result.stderr)
result = subprocess.run([sys.executable, str(SCRIPTS / "hooks/hooks.py"), "nope"], input="{}",
capture_output=True, text=True, timeout=10)
self.assertEqual(result.returncode, 1)
if __name__ == "__main__":
unittest.main()