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
145 lines
12 KiB
Markdown
145 lines
12 KiB
Markdown
# 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).
|