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

12 KiB
Raw Blame History

REFACTOR WAVE 5 — 감사(AUDIT) 결과와 실행 계획

작성: 2026-11-05 · 상태: 감사 완료 / 실행 전 (소스 무변경) 정책 정본: docs/REFACTOR_POLICY.md(DP1DP11, W3-, W4-) 계승. 본 문서는 Wave 5의 입력이며, 실행 후 docs/REFACTOR_WAVE5_REPORT.md로 결과를 남긴다. 하네스: .claude/skills/refactor-wave/SKILL.md (R1R8, 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):

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).