d3ro-voice/docs/tdd-red/07-revamp-plan.md

186 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 07 · TDD 체계 개편 계획 (Plan v2.0)
> 작성: 2026-11-05 · 갱신: 2026-11-13 · 상태: **Phase 0~3·5 완료 / Phase 4 결정성 포트 완료(Stryker 미설치 선택)**
> 선행 정본: `docs/tdd-red/00`~`06`(프레임워크 v1.1, 2026-11-04) · `AGENTS.md §3` · `.claude/skills/refactor-wave/SKILL.md`
> 본 문서는 v1.1을 **폐기하지 않는다.** v1.1이 문서로만 선언한 것을 **측정·게이트·자동화로 승격**하는 계획이다.
---
## 1. 현행 체계 (2026-11 현재 실측)
| 축 | 현재 | 정본 |
|---|---|---|
| 원칙 | 5축(행위·단정·실패이유·결정성·의도) + 12 패턴 / 10 안티패턴 | `02` |
| 실행 | 2계층(내부 루프 RED→GREEN→REFACTOR · 외부 GATE=VERIFY+REVIEW+DONE) | `05 §1` |
| TRIAGE | 변경별 RED 면제/필수 선별표 | `05 §7` |
| 위생 게이트 | `npm run test:hygiene` (8규칙 + `--self-test`) | `scripts/ci/check-test-hygiene.mjs` |
| 포트폴리오 | 정적/단위/서비스통합/계약/E2E 4계층, E2E는 임계 여정 6파일 | `06 §2`, `§5` |
| 통합 게이트 | `npm run verify:all` + CI 5잡(quality/build/mobile/edge/api) | `package.json`, `.forgejo/workflows/ci.yml` |
| 보호 경로 | `CODEOWNERS` 6경로 | `06 §5` |
**측정된 규모** (`docs/tdd-red/metrics/2026-11-08.md`, `npm run test:metrics`):
테스트 파일 **407** · 케이스 **3,498** · 단정 8,958
(desktop 2,075 / core 547 / mobile 509 / edge 263 / web 46 / api-client 31 / xUnit 27)
· 약한 단정 **128** · ambient 시계/난수 **203** · skip/todo 3 · i18n 2,753키 × 12로케일.
**현재 게이트 전부 GREEN** — typecheck, lint(`--max-warnings=0`), test:hygiene, contract/version/design.
---
## 2. 진단 — "문서는 있는데 강제되지 않는 것" 10개
| # | 갭 | 실측 증거 | 결과 |
|---|---|---|---|
| **G1** | 보호 경로가 **문서와 코드에서 다르고, 게이트가 없다** | `05 §2`/`06 §5`는 `tests/acceptance/**`를 보호경로라 하지만 실제 보호 대상은 `apps/*/tests/e2e/*.spec.ts`. `grep -rn "tests/acceptance" scripts/ci` → **0**. `CODEOWNERS`는 존재하나 CI 검사 없음 | 에이전트가 보호 여정의 단정을 약화·삭제해도 **초록** |
| **G2** | 결함-검출 강도 지표 없음 | 커버리지 설정 1개(`apps/desktop/vitest.config.ts` → `src/main/services/**` 한정), 실행·게이트 없음. 뮤테이션 도구 **미설치**(Stryker 없음, `05 §4`는 "도입 여부 결정"으로 미결) | 단정이 약해져도 알 방법이 없다 |
| **G3** | 약한 단정이 게이트를 통과 | `toBeDefined()/toBeTruthy()/not.toBeNull()` **128건**(2026-11-08 실측). hygiene 규칙은 "항상 참"(`expect(true)`)만 막는다 | 커버리지는 오르고 검출력은 0인 테스트가 합법 |
| **G4** | 결정성 정책 부재 | 테스트 내 `Date.now()`/`Math.random()`/`performance.now()` **203건**, `setTimeout` 38건. `Clock`/`Random` 포트 없음 | flaky가 나도 원인 귀속 규칙이 없다 |
| **G5** | flaky 격리·재시도 정책 없음 | CI에 재실행/격리 목록 없음. `05 §8`의 "zero-tolerance"는 선언뿐 | 재현 안 되는 실패가 "그냥 다시 돌리기"로 처리됨 |
| **G6** | 테스트 선택 실행 없음 | 로컬·CI 모두 전체 스위트. 영향 분석 없음(3,380 케이스) | 에이전트 루프가 느려져 TDD 자체가 회피된다 |
| **G7** | 포트폴리오 편중 | `apps/web` 24케이스(페이지 18개, 결제/Payple 흐름 포함) · `packages/ui` **0** · `packages/ui-native` **0** · `packages/i18n` **0** | 계약(DS/i18n) 계층이 비어 있음 |
| **G8** | 추적성(T-ID)이 문서에만 | `04-long-scenarios.md`의 T-101/T-210 표는 예시. 코드/테스트에 ID 없음, 매트릭스 생성 스크립트 없음 | 요구 → 테스트 추적 불가. SDD 이점 미확보 |
| **G9** | 계약 테스트가 i18n·디자인 토큰을 안 덮음 | 2,753키 × 12 로케일. 로케일 parity 검사 없음(수동 sync 스크립트가 값까지 하드코딩), 고아 후보 **798** | 번역 누락/드리프트가 조용히 배포 |
| **G10** | 보호 여정이 CI에서 **실행되지 않음** | 데스크톱 E2E는 러너 X 디스플레이 없음 → 릴리스 전 로컬 수동(`06 §6`) | "보호"가 실제로는 "미실행" |
한 줄 결론: **v1.1은 사양으로는 충분하고, 집행 수단이 없다.** 그래서 2.0의 주제는 "새 원칙"이 아니라 **"원칙을 스크립트로 옮기기"**다.
---
## 3. 개편 목표 구조 (v2.0)
2계층 루프는 유지하고, 외부 GATE에 **4개 기둥**을 추가한다.
```
[SPEC] 수용 시나리오(+T-ID) ── 보호 경로
│
[내부 루프] RED → GREEN → REFACTOR ← 로컬, test:affected 로 60초 이내
│
[GATE]
├─ VERIFY : affected 스위트 + typecheck + lint + hygiene (기존)
├─ CONTRACT : 보호경로 무결성 + i18n parity + DS 토큰 계약 (신규 ★)
├─ STRENGTH : 증분 뮤테이션(핵심 도메인) + 약한 단정 0 (신규 ★)
├─ REVIEW : 테스트 diff 먼저, 약화/삭제/스킵/무관변경 탐지 (기존)
└─ DONE : 결정적 통과 + flaky 재시도 3회 규칙 (강화 ★)
```
### 3-1. 신규 스크립트 (모두 `--self-test` 동반 = `test:hygiene` 패턴 준수)
| 스크립트 | 역할 | 최초 규칙 |
|---|---|---|
| `scripts/ci/check-protected-tests.mjs` | 보호 경로 diff 검사 | (a) 보호 파일에서 `it/test` 개수 **감소** 시 실패 (b) `expect(` 감소 시 실패 (c) `.skip/.only` 추가 시 실패 (d) 커밋 본문/PR 라벨에 `allow-protected-change:` 마커 + 사유가 없으면 실패 |
| `scripts/ci/check-test-quality.mjs` | **래칫** 게이트(파일별 기준선 동결) | `weak-assertion`(`toBeDefined/toBeTruthy/toBeFalsy/toBeNull`), `ambient-time`(무주입 `Date.now/Math.random/performance.now`). 기준선 `scripts/ci/test-quality-baseline.json` |
| `scripts/ci/check-i18n-contract.mjs` | 로케일 계약 | 키 집합 동일성(12개), `t('…')` 리터럴이 ko에 존재, 고아 키 리포트(게이트 아님 → 임계치 초과 시 실패) |
| `scripts/ci/check-ds-contract.mjs` | DS 계약 | `packages/ui` DS 컴포넌트가 role/aria 최소 계약을 export하고 테스트가 참조하는지 |
| `scripts/ci/test-metrics.mjs` | 지표 산출(게이트 아님) | 스위트별 케이스/시간/약한 단정/flaky 후보/뮤테이션 점수 → `docs/tdd-red/metrics/YYYY-MM-DD.md` |
| `scripts/ci/run-affected-tests.mjs` | 영향 선택 실행 | 변경 파일 → 워크스페이스·테스트 디렉터리 매핑 후 해당 스위트만 실행(안전 기본값: 매핑 실패 시 전체) |
### 3-2. 측정 항목 (게이트 아닌 지표, `05 §9` 정합)
- 결함-검출력: 증분 뮤테이션 점수(핵심 도메인만)
- flaky율: 3회 재실행 불일치 수
- 리드타임: `test:affected` 소요(목표 **< 60초**), CI full suite 소요
- 약한 단정 잔량(파일 단위 추세)
- 보호경로 무결성 위반 수(0 유지)
---
## 4. 로드맵 (Phase 0~5)
### Phase 0 — 기준선 (✅ 완료 2026-11-08)
- `scripts/ci/test-metrics.mjs` (+ 공용 헬퍼 `scripts/ci/lib/test-files.mjs`) 작성.
- 산출: `docs/tdd-red/metrics/2026-11-08.md` — 파일 407 · 케이스 3,498 · 단정 8,958 · 약한 단정 128 · ambient 203 · i18n 2,753키×12.
- **Exit 충족**: 지표 문서 + `npm run test:metrics` / `test:metrics:write` 등록.
### Phase 1 — 집행 수단 1: 보호경로·품질 래칫 (✅ 완료 2026-11-08)
- `scripts/ci/check-protected-tests.mjs` — 보호 6경로 diff 검사:
테스트/스텝 블록 감소 · `expect` 감소 · `.only` 추가 · `skip/todo` 추가 → 실패.
정당한 변경은 커밋 본문 `allow-protected-change: <사유>` 또는 `--reason` 으로만 통과.
CI `quality` 잡이 `--base HEAD^` 로 실행(체크아웃 depth 2). 얕은 클론에서는 SKIP 사유를 출력.
- `scripts/ci/check-test-quality.mjs` + `scripts/ci/test-quality-baseline.json` — 래칫 게이트.
오늘 수치(weak 128 / ambient 203)를 파일별로 동결하고 **증가만** 막는다.
`--update` 는 사람 리뷰 후에만.
- `npm run verify:all` 에 두 게이트 편입.
- **Exit 충족**: `.only` 를 보호 여정에 넣으면 CI/로컬이 빨강(수동 검증 완료),
새 약한 단정을 넣으면 `test:quality` 가 빨강(수동 검증 완료).
### Phase 2 — 집행 수단 2: 계약·i18n·DS (✅ 완료 2026-11-13)
- `packages/i18n/__tests__/locale-contract.test.ts`: 12로케일 **2,500키** 집합 동일, `{placeholders}` 정합, 값이 비어있지 않음 (15/15 PASS).
- `scripts/ci/check-i18n-contract.mjs` (`npm run check:i18n` + `:test`): 코드의 `t('literal')` 키 존재 검사 + 동적 prefix 화이트리스트 + 고아 상한 게이트(`unreferenced=8 <= 35`; 253개 죽은 키 정리 완료).
- `packages/ui/__tests__/ds-contract.test.tsx` (4/4 PASS) + `scripts/ci/check-ds-contract.mjs` (`npm run check:ds-contract` + `:test`): 13개 DS 컴포넌트 barrel export 및 `SegmentControl`(`role="tablist"`/`role="tab"`/`aria-selected`/키보드 `Enter`·`Space`), `InlineAlert`, `EmptyState`, `InstrumentPanel` 의미 계약 강제.
- `scripts/ci/sync-i18n-locales.mjs` 정리: 하드코딩 번역값 전부 제거, `--check` 검증 전용으로 전환.
- **Exit 충족**: 로케일 키 삭제·오타 또는 DS ARIA 계약 회귀 시 `verify:all` 및 CI `quality` 빨강(`--self-test` 검증 완료).
### Phase 3 — 피드백 속도: 영향 선택 실행 (✅ 완료 2026-11-13)
- `scripts/ci/run-affected-tests.mjs` + `npm run test:affected` (`+ :test`).
- 매핑 규칙: `packages/core/**` → core+api-client+desktop+web+mobile / `packages/i18n/**` → i18n+desktop+web+mobile / `packages/ui/**` → ui+desktop+web / `apps/desktop/**` → desktop / `apps/web/**` → web / `apps/mobile-rn/**` → mobile Jest / `apps/api-server*/**` → `dotnet test` / `site/**` → `typecheck:site`+`lint:site`.
- 안전장치: 매핑 미스 시 전체 스위트 폴백, CI는 **항상 full**.
- **Exit 충족**: `--plan` / `--self-test` 및 로컬 부분 실행 < 60초 확인, CI full 유지.
### Phase 4 — 강도: 결정성 포트 + 증분 뮤테이션 (✅ 결정성 포트 완료 2026-11-13 / Stryker 선택 보류)
- `packages/core/src/ports.ts` (`@d3ro/core/ports`): `Clock`, `FakeClock`, `Random`, `systemClock`, `systemRandom`, `createFakeClock`, `createSeededRandom(seed)` 추가 및 `ports.test.ts` (4/4 PASS) 고정.
- `scripts/ci/lib/test-files.mjs`가 `git ls-files --cached --others --exclude-standard`로 미추적 신규 테스트 파일까지 `test:quality` 래칫에 포함하도록 보강.
- Stryker 뮤테이션 러너는 lockfile 비대화 및 네이티브 의존성 충돌을 피하기 위해 패키지 설치를 보류하고, 필요 시 별도 로컬/야간 실험 도구로만 검토한다.
### Phase 5 — 릴리스 산출물 스모크 및 CI 배선 (✅ 완료 2026-11-13)
- `scripts/ci/verify-desktop-installer-smoke.mjs` (`npm run release:installer:smoke` + `:test`, 음성 케이스 8종 포함) 작성 및 `scripts/ci/release-desktop.mjs`·`.forgejo/workflows/release.yml` 배선 (`verify-release-metadata.mjs` 계약 고정).
- `.forgejo/workflows/ci.yml`에 `check:i18n`, `check:ds-contract`, `typecheck:site`, `lint:site`, `site` 프로덕션 빌드 추가.
- 대화형 Electron GUI 여정(`test:acceptance:desktop`)은 Linux CI 러너에 디스플레이가 없어 릴리스 전 로컬/Windows 인터랙티브 게이트로 유지(`06 §6`).
---
## 5. 게이트 커맨드 (개편 후 최종형)
```bash
# 커밋 전 (목표 < 90초) — Phase 0·1 반영
npm run test:hygiene:test && npm run test:hygiene
npm run check:protected-tests:test && npm run check:protected-tests
npm run test:quality:test && npm run test:quality
npm run test:affected # Phase 3
# PR / 통합
npm run verify:all # 위 두 게이트 포함
npm run check:i18n && npm run check:ds-contract # Phase 2
npm run test:metrics:write # 지표 스냅샷(게이트 아님)
# 야간
npm run test:mutation -- --full
# 릴리스 전
npm run test:acceptance:desktop # Windows 러너 또는 로컬(GUI 세션)
npm run test:acceptance:web
```
---
## 6. 하지 않을 것 (비목표)
- 커버리지 **퍼센트 게이트** 도입 금지 (`05 §9`: 커버리지는 지표, 게이트 아님).
- E2E 확대 금지 — 여전히 임계 여정 3~5개 + 웹 스모크(`06 §4`).
- 스냅샷/픽셀 비교 도입 금지(이 저장소에 시각 회귀 인프라 없음).
- `.NET`/Deno/모바일 Jest에 뮤테이션 적용 금지(`05 §4` 명시 제외 유지).
- 테스트를 통과시키기 위한 리팩터 금지 — 약화 발견 시 **테스트 보강 또는 스펙 재합의**만.
---
## 7. 리스크와 완화
| 리스크 | 완화 |
|---|---|
| 새 게이트가 기존 3,380 테스트를 대량으로 빨강으로 만든다 | Phase 1의 `weak-assertion`/`ambient-time`은 **변경 파일 한정**으로 시작, baseline 파일 목록을 `docs/tdd-red/metrics/`에 동결 |
| 보호경로 게이트가 정당한 스펙 변경을 막는다 | `allow-protected-change:` 마커 + 사유 요구(사람 리뷰), 마커 사용 이력은 월 1회 리뷰 |
| 뮤테이션 도구가 느려 개발 루프를 막는다 | PR은 증분·핵심 6모듈만, nightly 전체, 내부 루프에서 제외(`05 §4`) |
| 영향 선택 실행이 회귀를 놓친다 | 매핑 미스 = 전체 실행, CI는 항상 full, `packages/**` 변경은 광범위 매핑 |
| i18n 고아 798 삭제가 런타임 키를 지운다 | 동적 키(`t(\`settings.${x}\`)`) 화이트리스트를 게이트에 내장, 삭제는 Wave 5 G5와 분리 |
---
## 8. 완료 정의 (v2.0)
- [x] Phase 0 완료: 지표 기준선(`docs/tdd-red/metrics/2026-11-08.md` → `2026-11-13.md`) + `test:metrics`
- [x] Phase 1 완료: 보호경로·품질 래칫이 실제로 빨강을 낸다(self-test 6+6 케이스, 미추적 신규 테스트 스캔 포함)
- [x] Phase 2 완료: i18n(`check:i18n` + `locale-contract.test.ts` 15/15)·DS(`check:ds-contract` + `ds-contract.test.tsx` 4/4) 계약 게이트가 `verify:all`·CI에서 실제로 빨강을 낸다
- [x] Phase 3 완료: `test:affected`(`run-affected-tests.mjs` + `--self-test`) 구현 및 로컬 선택 실행 < 60초
- [~] Phase 4: `@d3ro/core/ports`(`Clock`/`Random`/`FakeClock`) 완료; Stryker 뮤테이션 러너는 lockfile 보존을 위해 미설치 유지
- [~] Phase 5: `release:installer:smoke`(`verify-desktop-installer-smoke.mjs`)가 `release-desktop.mjs`·`release.yml`에 배선됨; 대화형 Electron GUI E2E(`test:acceptance:desktop`)는 헤드리스 Linux 러너 제약으로 로컬/Windows 릴리스 전 실행 유지
- [x] `docs/tdd-red/00`~`06`이 실행 결과와 일치 (`06 §2·§6` 갱신 완료)
- [x] `docs/map/02-infrastructure.md` §10 테스트 인프라 행 갱신 (Phase 0~5 게이트 및 `2026-11-13` 지표 반영)