feat(hooks)!: 편집 직후 포맷·레이어·문서 알림과 migration 차단 훅을 건다
지금은 지켜야 할 규칙이 모두 문서에만 있다. 포맷·레이어 위반·문서 검사 실패는 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행.
This commit is contained in:
@@ -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`를 돌린다. 편집 훅이 실패 줄을 먼저 알려 준다.
|
||||
|
||||
@@ -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
|
||||
|
||||
+38
-1
@@ -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}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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절, 보고 형식은 소유자 전역 설정이다.
|
||||
|
||||
@@ -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/<leaf>/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` 머리의 상수를 맞춘다. 훅이 맞지 않으면 그 항목을 지운다 |
|
||||
|
||||
@@ -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 전체를 읽는다 |
|
||||
|
||||
나눌 때 지킬 것:
|
||||
|
||||
@@ -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. 완료 기준
|
||||
|
||||
@@ -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 <desktop 호스트> … gradlew …` 실행이 없으면 턴을 한 번 막고 이유를 준다 | `decision: block`, 다음 Java 편집 전까지 한 번 |
|
||||
|
||||
- N5가 기억하는 것은 `.claude/hook-state/<session_id>.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`를 둔다.
|
||||
@@ -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"^(?P<leaf>src/.+?)/src/main/java/(?P<rest>.+\.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/<leaf>/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의 `<gradle-path>: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:]))
|
||||
@@ -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<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_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()
|
||||
@@ -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`에 한 줄을 더한다. 편집 훅이 목록에 있는 파일의 편집을 막는다.
|
||||
|
||||
## 테스트
|
||||
|
||||
|
||||
@@ -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를 포맷하지 않는다.
|
||||
|
||||
Reference in New Issue
Block a user