diff --git a/.claude/agents/backend-dev.md b/.claude/agents/backend-dev.md index 2188afa..fb9fd4b 100644 --- a/.claude/agents/backend-dev.md +++ b/.claude/agents/backend-dev.md @@ -34,7 +34,7 @@ tools: Read, Grep, Glob, Edit, Write, Bash, Skill ## 완료 기준 (실행하고 결과를 보고한다) ```bash -cd backend && npm run lint && npm run test && npm run build +cd backend && npm run lint && npm run type-check && npm run test && npm run build ``` - 에러 코드를 건드렸다면 `npm run sync:error-codes` 를 실행하고 **생성 파일까지 함께** 커밋 대상에 넣는다. diff --git a/.claude/agents/tester.md b/.claude/agents/tester.md index e40ee88..4fb97ac 100644 --- a/.claude/agents/tester.md +++ b/.claude/agents/tester.md @@ -40,10 +40,13 @@ tools: Read, Grep, Glob, Edit, Write, Bash, Skill ## 완료 기준 (실행하고 결과를 보고한다) ```bash -cd backend && npm run test -cd frontend && npm run test:unit +cd backend && npm run type-check && npm run test +cd frontend && npm run type-check && npm run test:unit cd flutter && flutter test ``` +- 테스트 파일도 타입 검사를 통과해야 한다. backend 의 jest(ts-jest)는 타입을 보지 않아 타입이 틀린 목·픽스처로도 + 테스트가 통과해 버린다 — `type-check` 가 그 차이를 잡는다 ([[testing]]). + - e2e 는 DB 가 필요하다. 로컬이면 개발 스택을 띄운 뒤 컨테이너 안에서 실행한다 ([[testing]]). - 실행하지 못한 수트가 있으면 **어느 것을 왜 못 돌렸는지** 반드시 적는다. 통과했다고 뭉뚱그리지 않는다. diff --git a/.claude/rules/checklist.md b/.claude/rules/checklist.md index 44bdab7..eeab55b 100644 --- a/.claude/rules/checklist.md +++ b/.claude/rules/checklist.md @@ -29,7 +29,8 @@ > 아래 항목은 `.github/workflows/ci.yml` 이 PR 마다 자동 검사한다. 로컬에서 먼저 통과시키면 CI 도 통과한다. - [ ] 주석은 한국어, 매직 넘버·하드코딩 문자열 없음 ([[coding-common]]) -- [ ] 린트/분석 통과 — backend `npm run lint`, frontend `npm run lint && npm run type-check`, flutter `flutter analyze` +- [ ] 린트/분석 통과 — backend `npm run lint && npm run type-check`, frontend `npm run lint && npm run type-check`, flutter `flutter analyze` + (backend 의 `type-check` 는 테스트 파일까지 본다 — 빌드는 spec 을 제외하고 jest 는 타입을 보지 않는다) (lint 스크립트에 `--max-warnings 0` 이 걸려 있어 **Warning 하나만 있어도 실패**한다. 자동 수정은 `npm run lint:fix`) - [ ] 변경 영역 테스트 통과 — backend `npm run test`, frontend `npm run test:unit`, flutter `flutter test` ([[testing]]) - [ ] 절대경로 alias 사용 (TS `@/`, Dart `package:`), 깊은 상대경로 없음 diff --git a/.claude/rules/testing.md b/.claude/rules/testing.md index 247a0ed..82764b6 100644 --- a/.claude/rules/testing.md +++ b/.claude/rules/testing.md @@ -14,7 +14,9 @@ description: 세 스택 공통 테스트 규칙 — 테스트 위치/네이밍, - **공유 계약은 반드시 테스트한다** — 아래 "계약 테스트" 절 참조. - **테스트는 결정적(deterministic)** 으로 — 외부 네트워크/시간/랜덤에 의존하지 않도록 모킹한다. - **커밋 전 실행** — 변경 영역의 테스트가 통과해야 한다. ([[checklist]]) -- **CI 가 강제한다** — `.github/workflows/ci.yml` 이 세 스택의 lint·test·build 와 에러 코드 동기화를 PR 마다 검사한다. +- **CI 가 강제한다** — `.github/workflows/ci.yml` 이 세 스택의 lint·type-check·test·build 와 에러 코드 동기화를 PR 마다 검사한다. +- **테스트 파일도 타입 검사를 통과해야 한다.** backend 의 ts-jest 는 타입을 보지 않고(isolatedModules) 빌드는 spec 을 제외하므로, + 타입이 틀린 목·픽스처로도 테스트가 통과해 버린다 — `npm run type-check` 가 테스트·e2e 까지 검사한다. - 테스트 설명(it/test 제목)은 한국어로 "무엇을 검증하는지" 명확히 작성한다. ## 스택별 위치·실행 diff --git a/.claude/skills/nestjs/SKILL.md b/.claude/skills/nestjs/SKILL.md index b34d490..96ea389 100644 --- a/.claude/skills/nestjs/SKILL.md +++ b/.claude/skills/nestjs/SKILL.md @@ -321,7 +321,8 @@ dc exec backend npm uninstall <패키지> - [ ] **DTO**: 모든 입력 DTO 에 `class-validator` + 한국어 메시지 + `@ApiProperty()`. - [ ] **Swagger**: 새 엔드포인트에 `@ApiTags`/`@ApiOperation` + `@ApiStandardResponse`/`@ApiErrorResponse`. - [ ] **경로 alias**: `@/` 사용 (`tsconfig.json` paths + jest `moduleNameMapper` 설정 완료). 깊은 상대경로 금지. -- [ ] **lint/test**: 커밋 전 `npm run lint` (`--max-warnings 0`) + `npm run test` 통과. 자동 수정은 `npm run lint:fix`. +- [ ] **lint/test**: 커밋 전 `npm run lint` (`--max-warnings 0`) + `npm run type-check` + `npm run test` 통과. 자동 수정은 `npm run lint:fix`. + `type-check` 는 테스트·e2e·스크립트까지 본다 — 빌드는 spec 을 제외하고 ts-jest 는 타입을 보지 않으므로(isolatedModules) 테스트 파일의 타입 오류는 여기서만 잡힌다. - [ ] **의존성 변경 시**: 호스트가 아니라 **컨테이너 안에서** `npm install/uninstall` (위 주의 항목 참조). 변경 후 Docker 빌드 확인. - [ ] **에러 던지기**: `HttpException` 직접 생성은 린트로 차단된다 — `BusinessException(code)` 사용. - [ ] **새 필수 env 추가 시**: `shared/config/env.validation.ts` 에 검증 규칙과 테스트를 함께 추가 ([[env-structure]]). diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 878aca3..16cd252 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -21,7 +21,7 @@ -- [ ] 린트/분석 통과 (Warning 0) · 변경 영역 테스트 통과 +- [ ] 린트/분석·타입 검사 통과 (Warning 0) · 변경 영역 테스트 통과 - [ ] 주석 한국어, 매직 넘버·하드코딩 문자열 없음 - [ ] 사용자 노출 실패는 모두 에러 코드와 함께 처리 (`BusinessException` / `error.code` 분기) - [ ] 에러 코드를 바꿨다면 `npm run sync:error-codes` 실행 후 생성 파일까지 커밋 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a0a6937..96c4ec8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,7 +12,7 @@ concurrency: jobs: backend: - name: Backend (lint · test · e2e · build) + name: Backend (lint · type-check · test · e2e · build) runs-on: ubuntu-latest # 멈춘 잡이 러너를 무한 점유하지 않도록 상한을 둔다 timeout-minutes: 20 @@ -53,6 +53,12 @@ jobs: - name: Lint run: npm run lint + # 테스트·e2e·스크립트까지 타입 검사한다. + # 빌드(tsconfig.build.json)는 spec 을 제외하고 ts-jest 는 타입을 보지 않아(isolatedModules) + # 이 단계가 없으면 테스트 파일의 타입 오류가 어디에서도 걸리지 않는다. + - name: Type check + run: npm run type-check + - name: Test run: npm run test diff --git a/README.md b/README.md index 6dc60ec..e958bc1 100644 --- a/README.md +++ b/README.md @@ -225,7 +225,7 @@ cd flutter && flutter pub get && flutter run ### 커밋 전 검사 ```bash -cd backend && npm run lint && npm run test && npm run build +cd backend && npm run lint && npm run type-check && npm run test && npm run build cd frontend && npm run lint && npm run type-check && npm run test:unit cd flutter && flutter analyze && flutter test ``` @@ -265,7 +265,7 @@ lint 는 `--max-warnings 0` 이라 경고 하나만 있어도 실패합니다. ├── docker-compose.dev.yml # 개발 오버라이드 (핫리로드, 포트 노출) ├── CLAUDE.md # 프로젝트 개요 + 공통 규칙 @import ├── .github/ -│ ├── workflows/ci.yml # lint·test·build + 에러 코드 동기화 검사 +│ ├── workflows/ci.yml # lint·type-check·test·build + 에러 코드 동기화 검사 │ └── pull_request_template.md ├── ci/ # CI 러너 (Gitea Actions) — 앱 스택과 분리 └── .claude/ diff --git a/backend/package.json b/backend/package.json index ccc5784..9d42fee 100644 --- a/backend/package.json +++ b/backend/package.json @@ -14,6 +14,7 @@ "start:prod": "node dist/main", "lint": "eslint \"{src,apps,libs,test,scripts}/**/*.ts\" --max-warnings 0", "lint:fix": "eslint \"{src,apps,libs,test,scripts}/**/*.ts\" --fix", + "type-check": "tsc --noEmit --incremental false -p tsconfig.json", "test": "jest", "test:watch": "jest --watch", "test:cov": "jest --coverage", diff --git a/backend/src/common/errors/error-codes.spec.ts b/backend/src/common/errors/error-codes.spec.ts index b92f411..6ee438c 100644 --- a/backend/src/common/errors/error-codes.spec.ts +++ b/backend/src/common/errors/error-codes.spec.ts @@ -2,6 +2,7 @@ import { HttpStatus } from '@nestjs/common'; import { ERROR_CODES, + ErrorCodeDefinition, FALLBACK_ERROR_CODE, getErrorDefinition, isErrorCode, @@ -45,7 +46,10 @@ describe('에러 코드 레지스트리', () => { }); it('클라이언트 전용 코드(AUTH_002)는 서버가 상태 역매핑으로 선택하지 않는다', () => { - const clientOnlyCodes = Object.entries(ERROR_CODES) + // ERROR_CODES 는 as const 라 clientOnly 가 없는 항목의 타입에는 그 키가 없다 — 공통 정의 타입으로 읽는다 + const definitions: [string, ErrorCodeDefinition][] = + Object.entries(ERROR_CODES); + const clientOnlyCodes = definitions .filter(([, definition]) => definition.clientOnly) .map(([code]) => code); diff --git a/ci/README.md b/ci/README.md index 9147ae6..d4b8992 100644 --- a/ci/README.md +++ b/ci/README.md @@ -63,7 +63,7 @@ GitHub Actions 는 잡이 VM 위에서 직접 돌기 때문에 관례가 다르 **`ci.yml`** — 모든 푸시·PR 에서 실행 -- `backend` — postgres 서비스 컨테이너를 띄워 단위 테스트와 e2e 를 실행 +- `backend` — lint·타입 검사 후 postgres 서비스 컨테이너를 띄워 단위 테스트와 e2e 를 실행 - `frontend` — lint·type-check·테스트 - `error-codes-sync` — 에러 코드 생성 파일 드리프트 검사