From 38891071d6a7ebb4c14e144a6c03163e05485ebc Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 22:06:50 +0900 Subject: [PATCH] =?UTF-8?q?feat(hooks)!:=20=ED=8E=B8=EC=A7=91=20=EC=A7=81?= =?UTF-8?q?=ED=9B=84=20=ED=8F=AC=EB=A7=B7=C2=B7=EB=A0=88=EC=9D=B4=EC=96=B4?= =?UTF-8?q?=C2=B7=EB=AC=B8=EC=84=9C=20=EC=95=8C=EB=A6=BC=EA=B3=BC=20migrat?= =?UTF-8?q?ion=20=EC=B0=A8=EB=8B=A8=20=ED=9B=85=EC=9D=84=20=EA=B1=B4?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 지금은 지켜야 할 규칙이 모두 문서에만 있다. 포맷·레이어 위반·문서 검사 실패는 desktop 게이트에서야 보이고, 이미 적용된 migration을 고쳐도 desktop의 AppliedMigrationImmutabilityTest가 돌 때까지 아무도 모른다. 소유자가 2026-11-07에 편집 훅이 그 파일 하나만 Gradle 없이 포맷·린트하고, 전체 검사는 턴 끝 넛지로, 되돌릴 수 없는 것만 막기로 정했다 (design-docs harness/01-harness-design.md 5절, 13절 Q6·Q7). scripts/hooks/hooks.py 하나에 이벤트 넷(표준 라이브러리만): - pre-edit H13: 편집 대상이 applied-migrations.sha256에 있는 migration이면 종료 코드 2로 막고 새 버전 파일을 더하라고 안내한다. - post-edit 포맷: src/**/*.java 한 파일을 google-java-format으로 맞춘다. 버전은 카탈로그 googleJavaFormat, jar는 Gradle 캐시에 이미 있는 것만 쓰고(받거나 설치하지 않음), 옵션은 Spotless 단계와 같게 --skip-reflowing-long-strings --replace. 이 옵션으로 Spotless 대상 파일 전부를 dry-run 하면 차이가 0이었다(차이는 Spotless를 쓰지 않는 build-logic뿐이라 훅도 제외한다). 파일이 바뀌면 다시 읽으라고 알린다. - post-edit N1: registry로 leaf를 찾고 import를 순수성 목록 (DomainPurityArchitectureTest, verifyApplicationCoreDependencyPurity와 같은 패키지)과 allowed_dependencies 전이 closure에 대 본다. - post-edit N2: 문서 편집 뒤 check-work-docs·check-docs의 실패 줄. - post-bash·stop N5: Java를 고친 뒤 ssh desktop gradlew 실행이 없으면 턴 끝을 한 번 막고 desktop 검증이나 못 돌린 이유를 쓰라고 한다. - 권한: 실제 .env·.env.local·.env.lane 읽기·쓰기 deny(예시 파일은 둠). 버린 대안: 편집 훅에서 검사 안 하기(설계 권함, 소유자가 자료 쪽으로 정함), 편집마다 desktop 원격 실행(왕복 비용), checkstyle 한 파일 (Gradle 없이 classpath를 맞출 수 없다. 린트는 N1이 맡는다). 위험: 이 세션에서 settings.json을 바꿔도 훅은 돌지 않았다. 훅은 세션이 시작할 때 읽힌다. 그래서 settings.json이 부르는 명령에 같은 입력을 넣어 확인했다. N1은 게이트의 일부만 본다. 정본은 architectureCheck다. 검증: python3 -m unittest discover -s scripts/tests rc=0(훅 시험 29, 그중 실제 포매터 시험은 이 노트북 캐시의 1.35.0 jar로 돌았다). 변이 시험: 조건 10개를 하나씩 끈 사본마다 시험이 1~2건 실패했다. 실제 운영 소스 3,230개에 N1을 돌려 걸림 0. 편집 한 번 훅 시간 Java 0.3초, 문서 1.2초. check-docs·check-work-docs·check-repo-layout rc=0. BREAKING CHANGE: 파생 서비스에도 같은 훅과 .env deny가 걸린다. docs/upgrade/2026-11-harness.md 2절 4행. --- .claude/rules/docs.md | 2 +- .claude/rules/settings-and-runtime.md | 2 +- .claude/settings.json | 39 ++- CLAUDE.md | 3 +- docs/upgrade/2026-11-harness.md | 1 + docs/work/delegate.md | 2 +- docs/work/operate.md | 4 +- scripts/hooks/README.md | 45 +++ scripts/hooks/hooks.py | 461 ++++++++++++++++++++++++++ scripts/tests/test_hooks.py | 400 ++++++++++++++++++++++ src/adapter/outbound/AGENTS.md | 2 +- src/build-logic/AGENTS.md | 2 +- 12 files changed, 954 insertions(+), 9 deletions(-) create mode 100644 scripts/hooks/README.md create mode 100644 scripts/hooks/hooks.py create mode 100644 scripts/tests/test_hooks.py diff --git a/.claude/rules/docs.md b/.claude/rules/docs.md index 58fb8eb2..136ce71c 100644 --- a/.claude/rules/docs.md +++ b/.claude/rules/docs.md @@ -9,4 +9,4 @@ paths: - 기록 문서(`docs/design/`, `docs/history/`, `docs/reviews/`, `docs/adr/`)는 맨 위 머리 블록만 고친다. - 진입 문서(`AGENTS.md`, 모든 `src/**/AGENTS.md`, `docs/work/`, `.claude/` 아래 문서) 본문에는 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 `docs/work/evidence.md`로 옮긴다. - 문서를 읽는 테스트가 있다. 태그 `document-contract`(main 단계)·`repository-contract`(PR)다. 고친 문서의 경로로 `git grep -n '<경로>' -- 'src/*.java'`를 해서 그 테스트를 찾고 desktop에서 돌린다. -- 고친 뒤 `python3 scripts/check-work-docs.py`와 `python3 scripts/check-docs.py`를 돌린다. +- 고친 뒤 `python3 scripts/check-work-docs.py`와 `python3 scripts/check-docs.py`를 돌린다. 편집 훅이 실패 줄을 먼저 알려 준다. diff --git a/.claude/rules/settings-and-runtime.md b/.claude/rules/settings-and-runtime.md index dda442cd..861e9cae 100644 --- a/.claude/rules/settings-and-runtime.md +++ b/.claude/rules/settings-and-runtime.md @@ -23,7 +23,7 @@ paths: - 새 설정 그룹은 typed settings class로 만든다. 흩어진 `@Value`보다 configuration properties와 settings class를 쓴다. - 새 settings class를 만들면 바인딩·값 검증 테스트를 더한다. - capability 모듈의 설정 prefix는 하나다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact constructor다(`docs/manual/10-capabilities.md` 기준 4, Redis 예외 포함). -- `src/.env.local`은 로컬 덮어쓰기다. 실제 `.env` 파일은 읽지도 고치지도 않는다. 키 계약은 `src/.env.example`과 `docs/registries/env-keys.yaml`이다. +- `src/.env.local`은 로컬 덮어쓰기다. 실제 `.env` 파일은 읽지도 고치지도 않는다(권한 설정이 막는다). 키 계약은 `src/.env.example`과 `docs/registries/env-keys.yaml`이다. - `application.yml`은 환경마다 안전한 기본값과 분명한 자리표시자만 담는다. ## Docker·Compose diff --git a/.claude/settings.json b/.claude/settings.json index 3a3d67f9..ba08091d 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,7 +1,44 @@ { "permissions": { "deny": [ - "Agent" + "Agent", + "Read(**/.env)", + "Read(**/.env.local)", + "Read(**/.env.lane)", + "Edit(**/.env)", + "Edit(**/.env.local)", + "Edit(**/.env.lane)" + ] + }, + "hooks": { + "PreToolUse": [ + { + "matcher": "Edit|Write|MultiEdit", + "hooks": [ + {"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/hooks.py pre-edit", "timeout": 10} + ] + } + ], + "PostToolUse": [ + { + "matcher": "Edit|Write|MultiEdit", + "hooks": [ + {"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/hooks.py post-edit", "timeout": 60} + ] + }, + { + "matcher": "Bash", + "hooks": [ + {"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/hooks.py post-bash", "timeout": 10} + ] + } + ], + "Stop": [ + { + "hooks": [ + {"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/hooks.py stop", "timeout": 10} + ] + } ] } } diff --git a/CLAUDE.md b/CLAUDE.md index c6029fd8..4df9a8b5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,5 +2,6 @@ ## Claude Code에서만 -- 권한은 `.claude/settings.json`, 경로별 규칙(테스트·설정·Docker·문서)은 `.claude/rules/`에 있다. 규칙은 그 경로의 파일을 열 때 읽힌다. +- 권한과 훅은 `.claude/settings.json`이다: 편집 직후 Java 한 파일 포맷·레이어 의존 알림·문서 검사, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단, 실제 `.env` 읽기 차단. 훅마다 하는 일과 시험은 `scripts/hooks/README.md`다. +- 경로별 규칙(테스트·설정·Docker·문서)은 `.claude/rules/`에 있다. 그 경로의 파일을 열 때 읽힌다. - 소유자 환경: Gradle·Docker·테스트는 desktop에서만 돈다(`docs/work/operate.md` 4.1절). 세션 규칙은 `docs/work/delegate.md` 4.3절, 보고 형식은 소유자 전역 설정이다. diff --git a/docs/upgrade/2026-11-harness.md b/docs/upgrade/2026-11-harness.md index 5de4e5e5..127155a8 100644 --- a/docs/upgrade/2026-11-harness.md +++ b/docs/upgrade/2026-11-harness.md @@ -14,3 +14,4 @@ | 1 | leaf·family 지역 규칙 문서가 `src/**/CLAUDE.md`에서 같은 폴더 `src/**/AGENTS.md`로 옮겨 갔다. 그 폴더 `CLAUDE.md`는 `@AGENTS.md` 한 줄이다 | 서비스가 leaf `CLAUDE.md`를 고쳤다면 merge에서 충돌이 난다. 고친 내용을 같은 폴더 `AGENTS.md`로 옮기고 `CLAUDE.md`는 한 줄로 둔다. 서비스가 새로 만든 leaf도 같은 모양으로 둔다. 서비스 문서·테스트가 `src//CLAUDE.md`의 내용을 읽으면 `AGENTS.md`로 바꾼다(`git grep -n 'CLAUDE\.md' -- docs src`) | | 2 | 루트 `AGENTS.md`가 규칙 정본이자 지도(40줄 이하: 비전·HARD-STOP·지도·맡은 일·검증·일하는 방식)가 됐다. 루트 `CLAUDE.md`는 `@AGENTS.md`와 Claude 전용 몇 줄이다. 옛 `AGENTS.md`의 절은 옮겨 갔다: 「Gradle 정책 권위」 → `src/build-logic/AGENTS.md`, 「테스트 전략」의 작성 규칙 → `.claude/rules/java-tests.md`(계층별 기준은 각 계층 `AGENTS.md` 「테스트」), 「모듈 책임」 → `src/adapter/inbound/AGENTS.md`·`src/adapter/outbound/AGENTS.md`·각 core `AGENTS.md`, 「부가 기능(capability) 모듈 규칙」 → `docs/manual/10-capabilities.md`, 「설정과 런타임」 → `.claude/rules/settings-and-runtime.md`, 「템플릿 재사용 체크리스트」 → 루트 `README.md` 「새 서비스로 시작하기」. 「Superpowers Workflow」·「강제 수준」·「금지된 지름길」·「작업 보고 규칙」은 HARD-STOP·전역 규칙과 같은 말이라 지웠다 | 서비스가 루트 `AGENTS.md`나 `CLAUDE.md`를 고쳤다면 merge에서 충돌이 난다. 서비스 고유의 줄은 새 `AGENTS.md`의 같은 절(40줄 안)이나 위 새 자리에 옮긴다. 서비스 문서가 옛 절 이름(「Gradle 정책 권위」 등)을 가리키면 새 자리로 바꾼다 | | 3 | `.claude/rules/`(경로별 규칙)를 추적한다. `.gitignore`에 `!.claude/rules/`를 더했다 | 서비스 `.gitignore`가 `.claude/*`를 무시하면 같은 줄을 더한다 | +| 4 | `.claude/settings.json`에 repo 훅을 걸었다(본체 `scripts/hooks/hooks.py`, 설명 `scripts/hooks/README.md`): 편집 직후 Java 한 파일 포맷과 레이어 의존 알림, 문서 검사 알림, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단. 실제 `.env`·`.env.local`·`.env.lane` 읽기·쓰기를 권한으로 막는다 | 서비스가 `.claude/settings.json`을 고쳤다면 두 쪽을 합친다. 훅은 `src/config/architecture/modules.json`, `src/gradle/libs.versions.toml`의 `googleJavaFormat`, `applied-migrations.sha256`을 읽으므로 그 경로를 옮긴 서비스는 `hooks.py` 머리의 상수를 맞춘다. 훅이 맞지 않으면 그 항목을 지운다 | diff --git a/docs/work/delegate.md b/docs/work/delegate.md index 076dd9fa..eb09419d 100644 --- a/docs/work/delegate.md +++ b/docs/work/delegate.md @@ -68,7 +68,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 | `src/build.gradle`, `src/app-bootstrap/build.gradle` | 라이프사이클과 기본 조립 | | `docs/registries/*.yaml` | 오류 코드·env 키·지표를 여러 기능이 함께 쓴다 | | `docs/architecture/*-api-surface.txt`, `docs/security/public-paths-snapshot.txt` | 생성되는 스냅숏이다 | -| 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/settings.json`·`rules/` | 모든 세션이 읽거나 모든 세션에 걸린다 | +| 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/settings.json`·`rules/`, `scripts/hooks/` | 모든 세션이 읽거나 모든 세션에 걸린다 | | `.github/workflows/*` | 단계 검사가 workflow 전체를 읽는다 | 나눌 때 지킬 것: diff --git a/docs/work/operate.md b/docs/work/operate.md index fe2313e9..04165e4d 100644 --- a/docs/work/operate.md +++ b/docs/work/operate.md @@ -28,7 +28,7 @@ > 이 절은 이 repo 소유자의 기계에 묶인 규칙이다. 공용 정본은 design-docs `conventions/delegation-loop.md` 11절이다. 다른 환경(파생 서비스 등)은 이 절만 자기 환경으로 바꾼다. -- 노트북에서는 git, grep, 파일 읽기, 문서 편집, `python3 scripts/*.py` 검사만 한다. **Gradle, Docker, Testcontainers, 테스트, 게이트, 성능 측정은 desktop에서 돌린다.** +- 노트북에서는 git, grep, 파일 읽기, 문서 편집, `python3 scripts/*.py` 검사만 한다. **Gradle, Docker, Testcontainers, 테스트, 게이트, 성능 측정은 desktop에서 돌린다.** 예외는 편집 훅의 한 파일 포매터 하나다(Gradle 없이 JVM 한 번, 캐시에 있는 jar만. 소유자 결정 2026-11-07, `scripts/hooks/README.md`). - desktop의 Gradle·Docker 실행은 모두 공유 잠금 `flock /tmp/claude-gates/heavy.lock`으로 감싼다. 짝 프론트 repo도 같은 desktop에서 같은 잠금을 쓴다. - desktop의 기존 checkout `~/workspace/clean-architecture-backend-template`은 여러 세션이 함께 쓴다. 그 `stash@{0}`는 소유자의 보관분이다. 건드리지 않는다. `git stash pop`·`drop`·`clear`와 이름 없는 `git stash`를 쓰지 않는다. - design-docs repo는 노트북 `~/workspace/desktop-server-git/design-docs`에 있다. @@ -106,7 +106,7 @@ ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree' - 템플릿 쪽에서 할 일: 파생 서비스가 따라 고쳐야 하는 변경은 `docs/upgrade/`의 안내에 행을 더하고 커밋 제목에 `!`를 단다. 안내 문서 형식은 `docs/upgrade/2026-11-maturity-review.md`다. - 파생 서비스가 유지할 게이트와 지워도 되는 템플릿 전용 게이트는 `docs/ci-cd/template-vs-consumer.md`다. - 파생 서비스의 동기화는 루트 `CLAUDE.md`를 걸러낸다. 그래서 파생 서비스는 자기 `CLAUDE.md`에 `@AGENTS.md` 한 줄을 두고, 지도(`AGENTS.md`)에서 `docs/work/README.md`를 가리켜야 한다. `docs/work/`는 걸러지지 않는다. -- `.claude/`의 추적 파일(`settings.json`의 Agent 도구 금지, `rules/`)은 함께 넘어간다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 Agent 도구를 쓰려면 그 파일을 자기 repo에서 고친다. +- `.claude/`의 추적 파일(`settings.json`의 권한과 훅, `rules/`)은 함께 넘어간다. 훅 본체는 `scripts/hooks/`다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 Agent 도구를 쓰려면 그 파일을 자기 repo에서 고친다. - 파생 서비스 쪽 병합과 그 게이트는 그 repo의 일이다. 템플릿 세션이 파생 서비스 repo를 고치지 않는다. ## 5. 완료 기준 diff --git a/scripts/hooks/README.md b/scripts/hooks/README.md new file mode 100644 index 00000000..c0d51d64 --- /dev/null +++ b/scripts/hooks/README.md @@ -0,0 +1,45 @@ +# repo 훅 + +Claude Code가 정해진 때에 대신 실행하는 명령이다. 연결은 `.claude/settings.json`, 본체는 `hooks.py` 하나, 시험은 `scripts/tests/test_hooks.py`다. 모델이 잊어도 돈다. + +```text +Edit·Write 직전 ──> pre-edit ──> H13 적용된 migration이면 막는다(종료 코드 2) +Edit·Write 직후 ──> post-edit ──> Java면 포맷 → N1 레이어 의존 알림, 문서면 N2 문서 검사 알림 +Bash 직후 ──> post-bash ──> desktop에서 Gradle을 돌렸으면 N5 기록을 비운다 +턴 끝 ──> stop ──> N5 Java를 고쳤는데 desktop 실행이 없으면 한 번 알린다 +``` + +## 1. 원칙 + +- 되돌릴 수 없는 것만 막는다. 나머지는 알리기만 한다(넛지). 알림은 종료 코드 0이고, 모델 컨텍스트에 몇 줄(최대 5줄)만 더한다. +- 훅은 게이트의 일부만 본다. 정본은 게이트(desktop `architectureCheck`, `spotlessCheck`, 문서 검사)다. 훅이 틀리면 훅을 고치거나 끄고, 게이트는 그대로 둔다. +- 노트북에서 Gradle·Docker를 돌리지 않는다. 포매터는 Gradle 없이 JVM 하나로 파일 하나만 맞춘다(소유자 결정 2026-11-07). +- 받거나 설치하지 않는다. 포매터 jar는 Gradle이 이미 캐시에 받아 둔 것만 쓴다. 없으면 건너뛰고 세션에 한 번 알린다. +- 표준 라이브러리만 쓴다. 되돌릴 수 없는 명령 차단(force push, 범위 밖 `rm -rf`, DB·볼륨 삭제)과 비밀 값 알림은 repo가 아니라 소유자 전역 훅과 하네스 플러그인 몫이다. + +## 2. 훅마다 + +| ID | 때 | 하는 일 | 결과 | +| --- | --- | --- | --- | +| H13 | PreToolUse `Edit\|Write\|MultiEdit` | `src/**/src/main/resources/db/migration/<키>`의 `<키>`가 `src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`에 있으면 막는다 | 종료 코드 2와 「새 버전 파일을 더한다」 안내 | +| 포맷 | PostToolUse `Edit\|Write\|MultiEdit` | `src/**/*.java`(build-logic과 `build/` 제외)를 google-java-format으로 맞춘다. 버전은 카탈로그 `googleJavaFormat`, jar는 Gradle 캐시, 옵션은 Spotless 단계와 같게 `--skip-reflowing-long-strings --replace` | 파일이 바뀌면 「다시 읽는다」 한 줄. 문법 오류면 첫 줄들 | +| N1 | 같은 때, `src/**/src/main/java/**/*.java` | registry로 그 파일의 leaf를 찾고 import를 본다: 순수성 목록(`DomainPurityArchitectureTest`, `verifyApplicationCoreDependencyPurity`와 같은 패키지), inbound의 persistence 접근, `dev.caskeleton.*`의 주인 leaf가 registry `allowed_dependencies`(전이 포함)에 있는지 | 「HARD-STOP N 의심」 줄 | +| N2 | 같은 때, `*.md` | `scripts/check-work-docs.py`와 `scripts/check-docs.py`를 돌린다 | 실패 줄. 고친 문서를 가리키는 줄이 있으면 그것만 | +| N5 | Stop | 이 세션에서 Java를 고친 뒤 `ssh … gradlew …` 실행이 없으면 턴을 한 번 막고 이유를 준다 | `decision: block`, 다음 Java 편집 전까지 한 번 | + +- N5가 기억하는 것은 `.claude/hook-state/.json`이다(git이 무시한다). +- 권한 쪽 차단: `.claude/settings.json`의 `permissions.deny`가 실제 `.env`·`.env.local`·`.env.lane` 읽기·쓰기를 막는다. `.env.example` 같은 예시는 막지 않는다. + +## 3. 시험 + +```bash +python3 -m unittest discover -s scripts/tests +``` + +- 고장 낸 입력(적용된 migration 편집, 도메인의 Spring import, 들여쓰기가 틀린 Java, 깨진 링크)에서 막힘·알림이 나오고, 맞는 입력에서 조용한지 본다. +- 실제 포매터 시험은 Gradle 캐시에 카탈로그 버전 jar가 있는 기계에서만 돈다. 그 밖에서는 가짜 `java`로 옵션·파일 전달·바뀜 감지를 본다. +- 훅을 고치면 조건을 끈 사본에서도 시험이 실패하는지 본다(변이 시험). 조건 하나를 끄는 것마다 시험 하나 이상이 실패해야 한다. + +## 4. 끄기 + +훅이 시끄럽거나 틀리면 `.claude/settings.json`에서 그 항목을 지우고, 이유를 커밋 본문에 쓴다. 개인적으로만 끄려면 `.claude/settings.local.json`(git이 무시한다)에 `"disableAllHooks": true`를 둔다. diff --git a/scripts/hooks/hooks.py b/scripts/hooks/hooks.py new file mode 100644 index 00000000..1d32adb3 --- /dev/null +++ b/scripts/hooks/hooks.py @@ -0,0 +1,461 @@ +#!/usr/bin/env python3 +"""Claude Code repo hooks: nudge right after an edit, block only what cannot be undone. + +Called by `.claude/settings.json`, one event per invocation, with the hook input JSON on stdin: + + python3 scripts/hooks/hooks.py pre-edit # PreToolUse Edit|Write|MultiEdit H13 + python3 scripts/hooks/hooks.py post-edit # PostToolUse Edit|Write|MultiEdit format, N1, N2 + python3 scripts/hooks/hooks.py post-bash # PostToolUse Bash records desktop Gradle runs + python3 scripts/hooks/hooks.py stop # Stop N5 + +What each ID does, and why it nudges instead of blocking, is in scripts/hooks/README.md. A nudge +exits 0 and adds at most a few lines to the model's context; only H13 exits 2. No hook runs Gradle +or Docker: the owner's laptop never does (docs/work/operate.md 4.1). The formatter is one JVM on +one file, from the jar Gradle already cached. Standard library only. The tests are +scripts/tests/test_hooks.py. +""" + +from __future__ import annotations + +import hashlib +import json +import os +import re +import shlex +import subprocess +import sys +from pathlib import Path + +REGISTRY = "src/config/architecture/modules.json" +CATALOG = "src/gradle/libs.versions.toml" +MIGRATION_MANIFEST = "src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256" +STATE_DIR = ".claude/hook-state" +EDIT_TOOLS = ("Edit", "Write", "MultiEdit") +MAX_LINES = 5 + +# --- formatter: the step Spotless runs (QualityConventionsPlugin), on one file ----------------------- +GJF_GROUP = "com.google.googlejavaformat/google-java-format" +# The Spotless step keeps long strings as written; the CLI reflows them unless told not to. +GJF_FLAGS = ("--skip-reflowing-long-strings", "--replace") +GJF_EXPORTS = tuple(f"--add-exports=jdk.compiler/com.sun.tools.javac.{part}=ALL-UNNAMED" + for part in ("api", "code", "file", "parser", "tree", "util")) +GJF_TIMEOUT = 25 +# Spotless is not applied to build-logic (it is its own build), so the hook leaves it alone too. +FORMAT_EXCLUDED = ("src/build-logic/",) +SKIPPED = "포맷을 건너뛰었다" + +# --- N1: the layer rules the gates hold, checked on the imports of one edited main source -------------- +# Mirrors DomainPurityArchitectureTest (DOMAIN_IS_PURE, DOMAIN_HAS_NO_LOGGER). +DOMAIN_FORBIDDEN = ("org.springframework.", "jakarta.persistence.", "javax.persistence.", "jakarta.servlet.", + "org.hibernate.", "lombok.", "org.slf4j.", "java.util.logging.", "ch.qos.logback.", + "org.apache.logging.log4j.") +# Mirrors VerifyApplicationCoreDependencyPurityTask and the application-core AGENTS.md forbidden list. +APPLICATION_FORBIDDEN = ("org.springframework.", "org.slf4j.", "ch.qos.logback.", "org.apache.logging.log4j.", + "io.micrometer.", "java.util.logging.", "jakarta.persistence.", "javax.persistence.", + "lombok.") +SHARED_FORBIDDEN = ("org.springframework.", "jakarta.", "javax.persistence.", "org.hibernate.", "lombok.") +# HARD-STOP 2: an inbound adapter reaching the store. +INBOUND_FORBIDDEN = ("org.springframework.data.repository.", "org.springframework.data.jpa.", + "org.springframework.data.mongodb.repository.", "jakarta.persistence.", "javax.persistence.") +IMPORT = re.compile(r"^\s*import\s+(static\s+)?([\w.]+)(\.\*)?\s*;", re.M) +PROJECT_PREFIX = "dev.caskeleton." +MAIN_JAVA = re.compile(r"^(?Psrc/.+?)/src/main/java/(?P.+\.java)$") + +# --- N2: the document checks a living document edit can break ------------------------------------------- +DOC_CHECKS = (("scripts/check-work-docs.py",), ("scripts/check-docs.py",)) +DOC_TIMEOUT = 20 + +# --- N5: a Bash command that ran Gradle on the desktop clears the pending Java edits -------------------- +DESKTOP_HOST = re.compile(r"desktop") + + +# ---------------------------------------------------------------------------------------------------- +# plumbing + + +def project_root(payload: dict) -> Path: + root = os.environ.get("CLAUDE_PROJECT_DIR") or payload.get("cwd") or os.getcwd() + return Path(root).resolve() + + +def relative(root: Path, file_path: str | None) -> str | None: + if not file_path: + return None + path = Path(file_path) + if not path.is_absolute(): + path = root / path + try: + return path.resolve().relative_to(root).as_posix() + except ValueError: + return None + + +def edited_path(payload: dict) -> str | None: + if payload.get("tool_name") not in EDIT_TOOLS: + return None + return relative(project_root(payload), (payload.get("tool_input") or {}).get("file_path")) + + +def context(event: str, lines: list[str]) -> str: + """The PostToolUse output that adds lines to the model's context without blocking.""" + text = "\n".join(lines[:MAX_LINES] + ([f"(… {len(lines) - MAX_LINES}줄 더)"] if len(lines) > MAX_LINES else [])) + return json.dumps({"hookSpecificOutput": {"hookEventName": event, "additionalContext": text}}, + ensure_ascii=False) + + +def state_file(root: Path, session_id: str) -> Path: + safe = re.sub(r"[^A-Za-z0-9_.-]", "_", session_id or "unknown") + return root / STATE_DIR / f"{safe}.json" + + +def load_state(root: Path, session_id: str) -> dict: + try: + return json.loads(state_file(root, session_id).read_text(encoding="utf-8")) + except (OSError, ValueError): + return {"java_edits": [], "reminded": False} + + +def save_state(root: Path, session_id: str, state: dict) -> None: + path = state_file(root, session_id) + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(json.dumps(state, ensure_ascii=False), encoding="utf-8") + + +# ---------------------------------------------------------------------------------------------------- +# H13 — an applied migration is never edited + + +def applied_migrations(root: Path) -> set[str]: + try: + text = (root / MIGRATION_MANIFEST).read_text(encoding="utf-8") + except OSError: + return set() + return {line.split()[1] for line in text.splitlines() if line.strip() and not line.startswith("#") + and len(line.split()) == 2} + + +def migration_key(path: str) -> str | None: + """`src//src/main/resources/db/migration/jpa/core/V1__x.sql` → `jpa/core/V1__x.sql`.""" + marker = "/src/main/resources/db/migration/" + if marker not in path or not path.endswith(".sql"): + return None + return path.split(marker, 1)[1] + + +def h13_message(root: Path, path: str | None) -> str | None: + key = migration_key(path) if path else None + if key is None or key not in applied_migrations(root): + return None + return (f"[H13 적용된 migration 편집 금지] {path}\n" + "이 파일은 이미 적용된 migration이다(" + MIGRATION_MANIFEST + "에 있다). Flyway가 기동마다 checksum을" + " 대조하므로 고치면 운영 DB가 뜨지 않는다.\n" + "대신 새 버전 파일(V<다음 번호>__<설명>.sql)을 더하고 sha256 목록에 한 줄을 더한다. 어떤 DB에도 적용된 적 없는" + " 파일이라 고쳐야 하면 소유자에게 묻는다.") + + +# ---------------------------------------------------------------------------------------------------- +# format — google-java-format on the one edited file + + +def catalog_version(root: Path, key: str) -> str | None: + try: + text = (root / CATALOG).read_text(encoding="utf-8") + except OSError: + return None + match = re.search(rf'^{re.escape(key)}\s*=\s*"([^"]+)"', text, re.M) + return match.group(1) if match else None + + +def gradle_cache() -> Path: + home = os.environ.get("GRADLE_USER_HOME") + return (Path(home) if home else Path.home() / ".gradle") / "caches/modules-2/files-2.1" + + +def version_key(version: str) -> tuple: + return tuple(int(part) if part.isdigit() else -1 for part in re.split(r"[.-]", version)) + + +def newest_jar(cache: Path, group_artifact: str, suffix: str = "") -> Path | None: + folder = cache / group_artifact + artifact = group_artifact.rsplit("/", 1)[1] + versions = sorted((v.name for v in folder.glob("*") if v.name.endswith(suffix)), key=version_key) \ + if folder.is_dir() else [] + for version in reversed(versions): + jars = sorted(folder.glob(f"{version}/*/{artifact}-{version}.jar")) + if jars: + return jars[0] + return None + + +def formatter_classpath(root: Path, cache: Path) -> tuple[list[Path] | None, str]: + version = catalog_version(root, "googleJavaFormat") + if version is None: + return None, f"{CATALOG}에 googleJavaFormat 버전이 없다" + jars = sorted(cache.glob(f"{GJF_GROUP}/{version}/*/google-java-format-{version}.jar")) + if not jars: + return None, f"google-java-format {version} jar가 Gradle 캐시({cache})에 없다" + guava = newest_jar(cache, "com.google.guava/guava", "-jre") + access = newest_jar(cache, "com.google.guava/failureaccess") + if guava is None or access is None: + return None, "guava jar가 Gradle 캐시에 없다" + return [jars[0], guava, access], version + + +def wants_format(path: str | None) -> bool: + return bool(path) and path.startswith("src/") and path.endswith(".java") \ + and not path.startswith(FORMAT_EXCLUDED) and "/build/" not in path + + +def format_java(root: Path, path: str, cache: Path | None = None) -> list[str]: + """Format lines for the model. A skip line starts with SKIPPED so the caller can say it once.""" + classpath, detail = formatter_classpath(root, cache or gradle_cache()) + if classpath is None: + return [f"{SKIPPED}: {detail}. 받거나 설치하지 않는다. desktop `./gradlew spotlessApply`가 맞춘다."] + target = root / path + before = hashlib.sha256(target.read_bytes()).hexdigest() + command = ["java", *GJF_EXPORTS, "-cp", os.pathsep.join(str(jar) for jar in classpath), + "com.google.googlejavaformat.java.Main", *GJF_FLAGS, str(target)] + try: + result = subprocess.run(command, capture_output=True, text=True, timeout=GJF_TIMEOUT) + except FileNotFoundError: + return [f"{SKIPPED}: `java`가 PATH에 없다. desktop `./gradlew spotlessApply`가 맞춘다."] + except subprocess.TimeoutExpired: + return [f"{SKIPPED}: google-java-format이 {GJF_TIMEOUT}초 안에 끝나지 않았다."] + if result.returncode != 0: + errors = [line for line in result.stderr.splitlines() if line.strip()][:3] + return [f"google-java-format {detail}가 {path}를 읽지 못했다(문법 오류일 수 있다):", *errors] + if hashlib.sha256(target.read_bytes()).hexdigest() != before: + return [f"google-java-format {detail}가 {path}를 Spotless와 같은 모양으로 다시 썼다. 다음 Edit 전에 다시 읽는다."] + return [] + + +# ---------------------------------------------------------------------------------------------------- +# N1 — imports of one edited main source against the registry and the layer purity rules + + +def load_registry(root: Path) -> list[dict]: + return json.loads((root / REGISTRY).read_text(encoding="utf-8")).get("modules", []) + + +def owning_leaf(modules: list[dict], path: str) -> dict | None: + owners = [m for m in modules if path.startswith(m["source_path"].rstrip("/") + "/")] + return max(owners, key=lambda m: len(m["source_path"])) if owners else None + + +def package_index(root: Path, modules: list[dict]) -> dict[str, set[str]]: + """Java package → the leaves whose main source set has a class in it.""" + index: dict[str, set[str]] = {} + for module in modules: + base = root / module["source_path"] / "src/main/java" + for directory, _, names in os.walk(base): + if any(name.endswith(".java") for name in names): + package = Path(directory).relative_to(base).as_posix().replace("/", ".") + index.setdefault(package, set()).add(module["id"]) + return index + + +def closure(modules: list[dict], start: str) -> set[str]: + edges = {m["id"]: m.get("allowed_dependencies", []) for m in modules} + seen, pending = {start}, [start] + while pending: + for target in edges.get(pending.pop(), []): + if target not in seen: + seen.add(target) + pending.append(target) + return seen + + +def owner_of(index: dict[str, set[str]], name: str) -> tuple[str, set[str]] | None: + """The longest package prefix of an imported name that some leaf owns (handles nested and static).""" + parts = name.split(".") + for end in range(len(parts), 1, -1): + package = ".".join(parts[:end]) + if package in index: + return package, index[package] + return None + + +def forbidden_prefixes(leaf: str) -> tuple[str, tuple[str, ...]] | None: + if leaf == "domain-core": + return "HARD-STOP 1", DOMAIN_FORBIDDEN + if leaf.startswith("application-"): + return "HARD-STOP 1·4", APPLICATION_FORBIDDEN + if leaf == "shared-contract": + return "shared-contract 금지", SHARED_FORBIDDEN + if leaf.startswith("adapter-inbound-"): + return "HARD-STOP 2", INBOUND_FORBIDDEN + return None + + +def stop_number(leaf: str, target: str) -> str: + if (leaf == "domain-core" or leaf.startswith("application-")) and target.startswith("adapter-inbound-"): + return "HARD-STOP 3" + if leaf.startswith("adapter-inbound-") and target.startswith("adapter-outbound-persistence"): + return "HARD-STOP 2" + return "HARD-STOP 5" + + +def boundary_findings(root: Path, path: str, source: str) -> list[str]: + if not MAIN_JAVA.match(path): + return [] + modules = load_registry(root) + leaf = owning_leaf(modules, path) + if leaf is None: + return [] + allowed = closure(modules, leaf["id"]) + index = package_index(root, modules) + rule = forbidden_prefixes(leaf["id"]) + findings = [] + for static, name, wildcard in IMPORT.findall(source): + imported = name + (".*" if wildcard else "") + if rule and any(imported.startswith(prefix) for prefix in rule[1]): + findings.append(f"- {rule[0]} 의심: `{leaf['id']}`가 `{imported}`를 import한다.") + continue + if not name.startswith(PROJECT_PREFIX): + continue + owner = owner_of(index, name) + if owner is None or owner[1] & allowed: + continue + target = sorted(owner[1])[0] + findings.append(f"- {stop_number(leaf['id'], target)} 의심: `{imported}`는 leaf `{target}`의 것인데" + f" `{leaf['id']}`의 registry allowed_dependencies(전이 포함)에 없다.") + if findings: + findings.insert(0, f"레이어 의존 알림(N1) {path}") + findings.append("정본은 게이트다: desktop `./gradlew architectureCheck`. 의도한 edge면 registry가 먼저다.") + return findings + + +# ---------------------------------------------------------------------------------------------------- +# N2 — the document checks, failures only + + +def wants_doc_check(path: str | None) -> bool: + return bool(path) and path.endswith(".md") and "/build/" not in path and not path.startswith(".claude/hook-state/") + + +def doc_findings(root: Path, path: str) -> list[str]: + failures: list[str] = [] + for script in DOC_CHECKS: + try: + result = subprocess.run([sys.executable, *script], cwd=root, capture_output=True, text=True, + timeout=DOC_TIMEOUT) + except subprocess.TimeoutExpired: + failures.append(f"- {script[0]}: {DOC_TIMEOUT}초 안에 끝나지 않았다") + continue + if result.returncode == 0: + continue + lines = [line.strip() for line in result.stderr.splitlines() + if line.startswith(" ") and line.strip()] + mine = [line for line in lines if path in line] + failures += [f"- {line}" for line in (mine or lines)] + if failures: + failures.insert(0, f"문서 검사 알림(N2) {path} 편집 뒤 실패 줄:") + return failures + + +# ---------------------------------------------------------------------------------------------------- +# N5 — Java changed and the desktop has not compiled it since + + +def ran_desktop_gradle(command: str) -> bool: + try: + words = shlex.split(command) + except ValueError: + words = command.split() + for position, word in enumerate(words): + if word.endswith("ssh"): + hosts = [w for w in words[position + 1:position + 5] if not w.startswith("-")][:2] + if any(DESKTOP_HOST.search(host) for host in hosts) and "gradlew" in command: + return True + return False + + +def turn_end_reason(state: dict) -> str | None: + edits = state.get("java_edits") or [] + if not edits or state.get("reminded"): + return None + shown = ", ".join(f"`{edit}`" for edit in edits[:3]) + (f" 외 {len(edits) - 3}개" if len(edits) > 3 else "") + return (f"[N5 턴 끝 알림] 이 세션에서 Java 파일 {len(edits)}개를 고쳤고({shown}) 그 뒤 desktop Gradle 실행이 없다. " + "컴파일과 테스트는 노트북이 아니라 desktop에서 소유 leaf의 `:check`로 한다" + "(docs/work/operate.md 4.1절). 이번 턴에 돌릴 수 없으면 완료를 말하지 말고, 보고의 확인 줄에 돌리지 못한 것과" + " 이유를 적는다(HARD-STOP 6). 이 알림은 다음 Java 편집 전까지 한 번만 나온다.") + + +# ---------------------------------------------------------------------------------------------------- +# events + + +def pre_edit(payload: dict) -> int: + message = h13_message(project_root(payload), edited_path(payload)) + if message: + print(message, file=sys.stderr) + return 2 + return 0 + + +def post_edit(payload: dict) -> int: + root = project_root(payload) + path = edited_path(payload) + if path is None or not (root / path).is_file(): + return 0 + lines: list[str] = [] + if wants_format(path): + state = load_state(root, payload.get("session_id", "")) + formatted = format_java(root, path) + if formatted and formatted[0].startswith(SKIPPED): + # The reason does not change within a session; saying it on every edit is noise. + formatted = [] if state.get("format_skip_reported") else formatted + state["format_skip_reported"] = True + lines += formatted + if path not in state["java_edits"]: + state["java_edits"].append(path) + state["reminded"] = False + save_state(root, payload.get("session_id", ""), state) + lines += boundary_findings(root, path, (root / path).read_text(encoding="utf-8")) + if wants_doc_check(path): + lines += doc_findings(root, path) + if lines: + print(context("PostToolUse", lines)) + return 0 + + +def post_bash(payload: dict) -> int: + command = (payload.get("tool_input") or {}).get("command", "") + if ran_desktop_gradle(command): + root = project_root(payload) + state = load_state(root, payload.get("session_id", "")) + state["java_edits"] = [] + state["reminded"] = False + save_state(root, payload.get("session_id", ""), state) + return 0 + + +def stop(payload: dict) -> int: + if payload.get("stop_hook_active"): + return 0 + root = project_root(payload) + state = load_state(root, payload.get("session_id", "")) + reason = turn_end_reason(state) + if reason: + state["reminded"] = True + save_state(root, payload.get("session_id", ""), state) + print(json.dumps({"decision": "block", "reason": reason}, ensure_ascii=False)) + return 0 + + +EVENTS = {"pre-edit": pre_edit, "post-edit": post_edit, "post-bash": post_bash, "stop": stop} + + +def main(argv: list[str]) -> int: + if len(argv) != 1 or argv[0] not in EVENTS: + print(f"usage: hooks.py {{{'|'.join(EVENTS)}}} < hook-input.json", file=sys.stderr) + return 1 + try: + payload = json.load(sys.stdin) + except ValueError: + return 0 + return EVENTS[argv[0]](payload if isinstance(payload, dict) else {}) + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/scripts/tests/test_hooks.py b/scripts/tests/test_hooks.py new file mode 100644 index 00000000..b5c1fa08 --- /dev/null +++ b/scripts/tests/test_hooks.py @@ -0,0 +1,400 @@ +"""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 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 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("src/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 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 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_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 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 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) -> None: + run_event("post-bash", {"session_id": "s1", "cwd": str(self.repo.root), "tool_name": "Bash", + "tool_input": {"command": command}}) + + 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 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() diff --git a/src/adapter/outbound/AGENTS.md b/src/adapter/outbound/AGENTS.md index 5246830f..9af08751 100644 --- a/src/adapter/outbound/AGENTS.md +++ b/src/adapter/outbound/AGENTS.md @@ -11,7 +11,7 @@ - 유스케이스 정책을 adapter에 둔다(HARD-STOP 4). - registry `allowed_dependencies`에 없는 adapter끼리의 edge(HARD-STOP 5). 허용 edge는 registry만 정한다. -- 이미 적용된 migration 파일을 고친다. 새 버전 파일을 더하고 `persistence-jpa`의 `src/test/resources/db/applied-migrations.sha256`에 한 줄을 더한다. +- 이미 적용된 migration 파일을 고친다. 새 버전 파일을 더하고 `persistence-jpa`의 `src/test/resources/db/applied-migrations.sha256`에 한 줄을 더한다. 편집 훅이 목록에 있는 파일의 편집을 막는다. ## 테스트 diff --git a/src/build-logic/AGENTS.md b/src/build-logic/AGENTS.md index 51480a45..76de3ad1 100644 --- a/src/build-logic/AGENTS.md +++ b/src/build-logic/AGENTS.md @@ -35,4 +35,4 @@ registry, settings, build-logic, 루트 라이프사이클이 정하는 것을 ## 테스트 -- `./gradlew -p build-logic test --console=plain`(`src/`에서). build-logic은 Spotless 대상이 아니다. +- `./gradlew -p build-logic test --console=plain`(`src/`에서). build-logic은 Spotless 대상이 아니다. 편집 훅도 이 폴더의 Java를 포맷하지 않는다.