d3ro-voice/docs/REFACTOR_WAVE5_AUDIT.md
Yun Chan 42583cc96b test(infra): add test-system metrics baseline (TDD 2.0 Phase 0)
docs/tdd-red/07-revamp-plan.md Phase 0 — "측정 없는 개편은 없다"의 첫 단계.
게이트가 아니라 지표다 (05 §9: 커버리지·강도는 지표, 완료 조건 아님).

추가:
- scripts/ci/test-metrics.mjs — 스위트별 파일/케이스/단정/약한 단정/ambient/스킵,
  i18n 로케일 수·키 수를 markdown 또는 JSON 으로 산출 (--write 로 날짜 문서 생성)
- scripts/ci/lib/test-files.mjs — 테스트 파일 판정·계수 공용 헬퍼
  (test:hygiene 과 같은 패턴을 쓰도록 한 곳에 모음)
- docs/tdd-red/metrics/2026-11-08.md — 오늘 기준선

측정 결과 (기준선):
- 파일 407 · 케이스 3,498 · 단정 8,958
- 약한 단정(toBeDefined/toBeTruthy/toBeFalsy/toBeNull) 128
- ambient 시계/난수(Date.now/Math.random/performance.now) 203
- skip/todo 3 · i18n 2,753키 × 12로케일

문서:
- 07-revamp-plan.md: 상태를 "Phase 0 완료"로 갱신, 측정치를 추정치(3,380/106/169)에서
  실측치로 교정
- REFACTOR_WAVE5_AUDIT.md: Wave 5 감사 결과(실행 입력) 편입

검증: node scripts/ci/test-metrics.mjs --write / --json GREEN,
      npm run test:metrics GREEN
2026-11-08 21:08:35 +09:00

145 lines
12 KiB
Markdown
Raw Permalink 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.

# REFACTOR WAVE 5 — 감사(AUDIT) 결과와 실행 계획
> 작성: 2026-11-05 · 상태: **감사 완료 / 실행 전** (소스 무변경)
> 정책 정본: `docs/REFACTOR_POLICY.md`(DP1~DP11, W3-*, W4-*) 계승. 본 문서는 Wave 5의 **입력**이며,
> 실행 후 `docs/REFACTOR_WAVE5_REPORT.md`로 결과를 남긴다.
> 하네스: `.claude/skills/refactor-wave/SKILL.md` (R1~R8, P1~P12)
---
## 0. 기준선 (감사 시점에 실제로 돌린 게이트)
| 게이트 | 결과 | 비고 |
|---|---|---|
| `npm run typecheck` (전 워크스페이스) | **GREEN** | desktop/web/admin/packages 전부 |
| `npm run lint` | **GREEN** (`--max-warnings=0`) | desktop/web/admin/packages |
| `npm run test:hygiene` | **GREEN** (400 test files) | `.only`/무근거 skip/항상참 단정/`waitForTimeout` 없음 |
| `npm run contract:check` · `version:check` · `check:design` | **GREEN** | 드리프트 0 |
| `any` · `console.log` · `TODO/FIXME` | **0건** | 표면 위생은 이미 포화 |
**해석**: 표면 규칙(any/console/토큰/i18n 리터럴)은 Wave 1~4에서 소진됐다. Wave 5의 수확은
**계약 드리프트 · 테스트만 통과하는 코드 · 3회 이상 중복 · 게이트 공백**에 있다.
측정 재현(로컬 스크립트, `scratch/`는 gitignore):
```bash
node scratch/dead-exports.mjs # 928 export 중 dead 43 / test-only 12
node scratch/dead-modules.mjs # app 레이어 미import 모듈 8 (엔트리 5 제외 → 2~3 실 후보)
node scratch/dupe-audit.mjs # 앱 간 동명 함수 80쌍, 최장 함수(컴포넌트) 목록
node scratch/i18n-audit.mjs # 2753 키 × 12 로케일, 고아 후보 798
```
---
## 1. 발견 (판정: DELETE / REWIRE / REFACTOR / KEEP)
### P0 — 사용자 약속·보안 (문서가 주장하는데 코드에 호출자가 없음)
| ID | 확신도 | 판정 | 근거 | 왜 지금 |
|---|---|---|---|---|
| **W5-01** | HIGH | **REWIRE**(불가 시 DELETE+주장 철회) | `packages/core/src/utils/pii-redactor.ts:1-3`("클라우드 전송 전 민감 데이터 자동 마스킹"), `packages/core/src/utils/secure-memory.ts`, 재export `packages/core/src/index.ts:18`. 프로덕션 호출 **0** — 유일 참조는 `apps/desktop/tests/red/pii-redactor.usecase.test.ts` (`grep -rn redactPII apps server` → 0) | 테스트는 "ZDR/마스킹 동작"을 초록으로 증명하는데 실제 전송 경로엔 배선이 없다. **컴플라이언스 주장과 코드가 불일치** |
| **W5-02** | HIGH | **DELETE** | `packages/core/src/ipc-channels.ts:60-73`(TTS 채널 9개), `packages/core/src/types.ts:247-292`(TTS 타입 7개). preload에 TTS 네임스페이스 없음, `apps/desktop/src/main/ipc/`에 tts 핸들러 없음. 실제 재생은 `TTSPlaybackService`가 자체 표면으로 처리 | 죽은 IPC 계약이 SSOT에 남아 있으면 "이 채널로 붙이면 된다"는 오해를 만든다 |
### P1 — 계약 드리프트 (타입은 SSOT에 있는데 소비자가 안 씀)
| ID | 확신도 | 판정 | 근거 |
|---|---|---|---|
| **W5-03** | HIGH | 채널 살아있음 → **REWIRE**, 채널 죽음 → **DELETE** | `packages/core/src/types.ts` 데드 27: `TTSSpeakParams`(270), `TTSSpeakResult`(276), `SetTTSVoiceParams`(280), `DownloadVoiceParams`, `TTSStatusChangedEvent`(288), `SpeakingStateChangedEvent`, `PullModelParams`(356), `LLMPullProgressEvent`(370), `HistoryExportParams`(744), `ShowRecordingTipParams`(825), `ShowResultPopupParams`(831), `TipMeasuredParams`(836), `TipStateChangedEvent`, `TipPrepareEvent`, `TipShowEvent`, `ActiveAppInfo`, `ShowNotificationParams`, `OpenExternalParams`, `InsertTextParams`, `InsertTextResult`, `StatsQueryParams`, `DailyStats`, `WeeklyStats`, `RAGChunk`, `MeetingGenerateDocResult`, `DiarizationResult`, `CreateSupportTicketParams` |
실행 규칙(P1 재검증): 각 타입마다 **채널/핸들러가 살아있는지** 먼저 grep한다.
- 살아있음 → preload/handler가 코어 타입을 import하도록 **REWIRE**(SSOT 복구). 예: `text:insert`는 서비스 내부 호출로 남아 `InsertTextParams`가 사장 → DELETE.
- 죽음 → 타입 삭제. `Statistics`/`RAG`/`support` 계열은 실제 IPC 표면 확인 후 결정.
### P2 — 데드 모듈·토큰
| ID | 확신도 | 판정 | 근거 |
|---|---|---|---|
| **W5-04** | HIGH | DELETE | `apps/desktop/src/renderer/components/ProBadge.tsx` (65줄, 자기 참조만) · `apps/admin/src/lib/supabase-server.ts` (web 사본과 동일 래퍼, import 0) |
| **W5-09** | MED | DS 공개 API 여부 확인 후 DELETE | `packages/ui/src/theme.ts`: `d3roSpace`, `d3roWeight`, `d3roMotion`, `darkTheme`, `lightTheme`, `getModePalette` / `packages/ui-native/src/theme.ts`: `d3roNativeSpace`, `d3roNativeWeight`, `d3roNativeMotion`, `d3roNativeOverlayShadow`, `D3roNativePaletteKey` — 참조 0 |
| **W5-10** | MED | REFACTOR | hex 폴백 10건: `packages/ui/src/components/ds/AudioVisualizerBar.tsx:26-33`, `GradientWave.tsx:30-38` — `#60a5fa/#3b82f6/#818cf8/#a78bfa`가 테마 값과 이중 정의(DP1 정신 위반) |
`KEEP`(삭제 금지, 사유 명시): `apps/desktop/src/preload/popup.ts`(electron-vite entry) · `apps/*/src/proxy.ts`(Next 미들웨어) · `apps/admin/src/instrumentation.ts` · `*.d.ts` · `packages/core/src/constants.ts:WAVE_BAR`(외부 계약 아님, 화면 고유 수치 P4).
### P3 — 3회 이상 중복 (DP7 위반, 실측)
| ID | 확신도 | 판정 | 중복 |
|---|---|---|---|
| **W5-05** | HIGH | REFACTOR → `packages/core/src/{guards,csv,format}.ts` | `isRecord` **27**정의 · `requireUuid` **14** · `requireUserId` **8** · `formatDuration` **9** · `escapeLikePattern` **3**(`apps/desktop/src/main/db/like-pattern.ts:12`, `apps/web/src/lib/dictionary-client.ts:109`, `apps/mobile-rn/src/features/dictionary/dictionary-service.ts:154` — 셋 다 동일 정규식) · `csvCell` **3** · `parseCsv`/`parseCsvRows`/`serializeDictionary`/`parseDictionaryFile` **3** |
| **W5-06** | MED | REFACTOR → `packages/core/src/unified-search.ts` | 통합검색 랭킹·발췌 이중 구현: `apps/desktop/src/main/services/UnifiedSearchService.ts`(264줄) vs `apps/mobile-rn/src/features/search/unified-search-service.ts`(459줄) — `includesQuery`/`recordResult`/`meetingResult`/발췌 생성 동일 규칙, 데이터 접근만 다름 |
| **W5-07** | MED | REFACTOR(역할 순서만 core로) | 권한 계층 2벌: `apps/admin/src/lib/admin-guard.ts`(71줄) vs `server/supabase/functions/_shared/admin-auth.ts`(74줄) — manager<admin<super_admin |
주의(W5-05): 오류 타입이 앱마다 다르므로 `throw`를 공용화하지 않는다. **판정 함수만** core로 올리고
각 앱은 `if (!isUuid(x)) throw new XError(...)` 형태로 유지한다(가드의 실패 표면은 앱 소유).
### P4 — i18n 위생
| ID | 확신도 | 판정 | 근거 |
|---|---|---|---|
| **W5-08** | MED | REFACTOR | ① `scripts/ci/sync-i18n-locales.mjs`가 **번역 값 40여 개를 스크립트 안에 하드코딩**(ko/en) 후 JSON에 주입 — W3 "손으로 옮겨 적은 사본 금지"의 변형 위반. ② 로케일 간 값이 ko와 동일한 키 52~65개(미번역). ③ 고아 후보 **798**/2753 (정적 `t('…')` 기준). ④ `--check` 게이트 부재 → 드리프트가 조용히 통과 |
### P5 — 구조(대형 파일) — churn 근거가 있는 것만
| ID | 확신도 | 판정 | 근거 |
|---|---|---|---|
| **W5-11** | MED | REFACTOR (순수 이동 P3) | `apps/desktop/src/renderer/components/SettingsModal.tsx:95` 단일 컴포넌트 **857줄** · `meeting/MeetingDetailTabs.tsx:98` **720** · `pages/MeetingModePage.tsx:61` **672** · `input-insights/InputInsightsView.tsx:106` **616** · `input-insights/InputConsentPanel.tsx:33` **584** · 서비스: `packages/core/src/typo-correction.ts` 2705 · `SuggestionService.ts` 2392(최근 churn 22회) · `InputTelemetryService.ts` 2205 |
### P6 — 게이트 공백
| ID | 확신도 | 판정 | 근거 |
|---|---|---|---|
| **W5-12** | HIGH | GATE 추가 | `site/`는 npm workspace 밖(`package.json` workspaces에 없음) → 루트 `lint`/`typecheck`/`test` 대상 아님. 마케팅·법률·다운로드 표면인데 정적 게이트 0. `site/src/i18n/index.ts`(231줄)도 독립 구현 |
---
## 2. 패치 그룹 (파일 비충돌 · 순수 정리와 기능 수정 분리)
| 그룹 | 내용 | 파일 영역 | 선행 |
|---|---|---|---|
| **G1** | W5-04 데드 모듈 + W5-09 데드 토큰 + W5-10 hex 폴백 | `apps/desktop/src/renderer/components/ProBadge.tsx`, `apps/admin/src/lib/supabase-server.ts`, `packages/ui/src/{theme,theme-vars}.ts`, `packages/ui-native/src/theme.ts`, `packages/ui/src/components/ds/*` | — |
| **G2** | W5-02 TTS 계약 삭제 + W5-03 타입 27건 REWIRE/DELETE | `packages/core/src/{types,ipc-channels}.ts`, `apps/desktop/src/preload/index.ts`, `apps/desktop/src/main/ipc/*` | — |
| **G3** | W5-01 PII/ZDR 배선 (**기능 변경**, 별도 커밋·별도 검증) | `packages/core/src/utils/{pii-redactor,secure-memory}.ts`, `apps/desktop/src/main/services/{CloudSTTService,AudioCaptureService}.ts`, 클라우드 프록시 경로 | 사용자 결정 필요(배선 vs 주장 철회) |
| **G4** | W5-05/06/07 중복 → core 추출 | `packages/core/src/{guards,csv,format,unified-search,admin-roles}.ts`(신규), `apps/{desktop,web,mobile-rn}/src/**`, `server/supabase/functions/_shared/admin-auth.ts` | G2 완료 후(같은 types.ts 접촉 회피) |
| **G5** | W5-08 i18n 스크립트 정리 + `--check` 게이트 | `scripts/ci/sync-i18n-locales.mjs`, `packages/i18n/src/locales/*.json`, `package.json` | — |
| **G6** | W5-12 site 정적 게이트 | `.forgejo/workflows/ci.yml`, root `package.json`, `site/tsconfig.json`, 가능하면 `site` eslint config | — |
| **G7** | W5-11 대형 파일 순수 이동 (**위험**, 화면별 1커밋) | renderer 컴포넌트/페이지 단위 | G1 완료 후(토큰 접촉 회피) |
각 그룹 검증(R7 축약): 잔여 식별자 grep → 변경 파일 lint → 해당 워크스페이스 테스트 →
모노레포 `typecheck` → (G3/G7은) `npm run dev` 수동 1회. `git add -A` 금지, 그룹당 1커밋.
---
## 3. 실행 전 사용자 결정이 필요한 4가지
1. **W5-01**: PII 마스킹/ZDR을 **실제 전송 경로에 배선**할 것인가, 아니면 코드·테스트·주장을 **삭제**할 것인가? (배선은 기능 변경이므로 Wave 5 범위 밖으로 빼는 선택도 가능)
2. **W5-03**: 살아있는 채널의 타입은 **REWIRE(SSOT 복구)** vs **타입 삭제(핸들러 인라인 유지)** 중 어느 쪽? (권장: REWIRE)
3. **W5-09**: `d3roSpace/Weight/Motion`, `darkTheme/lightTheme/getModePalette`는 외부 소비자를 위한 **DS 공개 API**로 유지할 것인가? (권장: 참조 0이면 삭제, 재도입은 필요 시)
4. **W5-11**: 대형 파일 분할을 이번 Wave에 포함할 것인가, 아니면 G1~G6만 하고 별도 Wave로 미룰 것인가? (권장: `SuggestionService`만, churn 22회 근거로)
---
## 4. 실행 순서 (권장)
```
G1(데드 모듈/토큰) → G2(TTS 계약) → G4(중복 추출) → G5(i18n) → G6(site 게이트) → G7(대형 파일)
↘ G3(PII 배선) — 별도 승인·별도 검증
```
G3만 "순수 정리 아님"으로 표시해 분리한다(W4-4 규칙). 나머지는 공개 IPC/payload 의미를 바꾸지 않는다.
---
## 5. 보고서에 남길 것 (실행 후)
- 그룹별 diff 요약 + 삭제/이동 건수(실측 재측정: `scratch/dead-exports.mjs` before/after)
- W5-03 각 타입의 live/dead 판정 표(REWIRE vs DELETE 근거)
- G7 diff 1:1 대조 결과(P2: 훅 체인·구독/해제·useEffect deps)
- false positive 기록(P1): 이번 감사에서 걸러낸 것 — 예: `AppUpdatePhase`는 같은 파일 내부 참조, `popup.ts`는 빌드 엔트리, `apps/web` 컴포넌트는 `@/` 별칭 import
- 남은 부채: i18n 고아 키 798(사용처 재확인 필요), `apps/web` 테스트 24건, `packages/ui` 테스트 0 → TDD 개편(`docs/tdd-red/07-revamp-plan.md`)으로 이관
---
## 6. 하네스 갱신 항목
- `docs/REFACTOR_POLICY.md`에 **Wave 5 섹션**(W5-1~W5-5) 추가 — 실행 착수 시.
- `.claude/skills/refactor-wave/SKILL.md` 누적 인덱스에 Wave 5 추가.
- `docs/map/10-feature-catalog.md` · `11-gap-backlog.md` — G1/G2/G4 완료 시 해당 기능 행 갱신(AGENTS.md §4).