TSK-009-05 TypeScript coverage 95

[ClarusIubar]

TSK-009-05 TypeScript coverage 95

Scope-ID: TSK-009-05
Issue: #328
Parent Issue: #323
Child Issue: #328
Branch: typescript-coverage-95
Status: in-progress
PR URL: TBD-TSK-009-05
Commit SHA: TBD-TSK-009-05
merge commit: TBD-TSK-009-05
CI evidence: TBD-TSK-009-05

Scope

React, Worker, scripts TypeScript 코드의 coverage gate를 statements, branches, functions, lines 각각 95% 이상으로 올리고, npm.cmd run test:coverage:ts가 95% threshold를 실제로 통과하도록 만든다.

이 child issue는 TypeScript coverage hard gate만 소유한다. Python coverage는 #329, QA Wiki traceability는 #330, 배포 확인과 UI/UX 기능 변경은 이 범위가 아니다.

Core Classification

Core: TSK-009-00
Parent Issue: #323
Rationale: UI/UX expectation tracking and 95% coverage gate parent 아래의 TypeScript coverage hard gate 실행 단위다.
Misroute blocked: Python coverage(#329), QA Wiki traceability(#330), UI/UX feature work, deployment debugging은 이 child issue 범위가 아니다.

문제 정의

Problem	Why it matters
test:coverage:ts는 실행 통과 상태지만 95% 목표에는 미달	coverage gate가 품질 회귀를 막지 못함
Statements/lines가 약 90%, branches가 약 73%	branch 경계와 예외 경로 테스트가 부족함
Functions가 95% 직전	일부 public boundary가 호출되지 않음

결정 사항

항목	결정
Branch	typescript-coverage-95
API contract	변경 없음
DB schema	변경 없음
User-facing copy	변경 없음
Auth/OAuth path	변경 없음
Scope	TypeScript tests/config coverage gate only

Out Of Scope

• 사용자-facing copy 변경
• API path, response shape, DB schema, OAuth 경로 변경
• Python coverage 작업(TSK-009-06 FastAPI coverage 95 #329)
• 배포 파이프라인 변경
• coverage 달성을 위한 exclude 범위 확대
• private implementation monkey patch 또는 import-only 테스트

Public Behavior And Interface / Data Flow Impact

Public behavior: npm.cmd run test:coverage:ts는 TypeScript coverage 네 지표가 모두 95% 이상일 때만 성공해야 한다.

Interface: Vitest coverage 설정과 test suite만 변경한다. production API/public response contract는 변경하지 않는다.

Data flow: Vitest coverage provider가 src, scripts, deploy/api-worker-shell production TypeScript를 측정하고 coverage summary를 출력한다.

Failure mode: 새 production TypeScript 코드가 coverage를 떨어뜨리면 coverage command가 실패해야 한다. coverage 달성을 위해 behavior 변경, API 변경, exclude 확대가 필요하면 중단한다.

Validation target: Statements >= 95%, Branches >= 95%, Functions >= 95%, Lines >= 95%.

Target Design

public tests and stable boundary tests
-> Vitest coverage provider
-> 95% threshold gate
-> CI/local failure on regression

Architecture Boundary Gate

Durability: durable

Architecture profile: Vitest config, public tests, script command boundary.

Responsibility map: coverage config는 threshold policy를 소유하고, 테스트 파일은 public behavior와 stable boundary를 검증한다.

Dependency direction: production code는 test helper에 의존하지 않는다. 테스트만 production public exports와 DOM/API/Worker/script boundary를 호출한다.

External dependency boundary: external network and browser APIs are mocked or isolated through existing test seams.

Validation seam: unit, integration, regression, e2e, and coverage tests use mocked DOM/API/Worker/script boundaries. Coverage is proven without live external services as the only proof.

Scope map: coverage 미달 보강은 TypeScript tests/config/scripts 범위에 한정한다.

Architecture risk: coverage 수치만 맞추기 위한 private implementation monkey patch나 무의미한 import-only 테스트를 금지한다.

Single-file exception: none expected.

Issue Structure

Parent issue:

• TSK-009-00 Epic: UI/UX expectation tracking and 95% coverage gate #323 TSK-009-00 Epic: UI/UX expectation tracking and 95% coverage gate - TSK-009-00 Epic: UI/UX expectation tracking and 95% coverage gate #323

Sub-issue:

• TSK-009-05 TypeScript coverage 95 #328 TSK-009-05 TypeScript coverage 95 - TSK-009-05 TypeScript coverage 95 #328

현재 coverage snapshot

• 기준 명령: npm.cmd run test:coverage:ts
• Statements: 95.45% (5416/5674)
• Branches: 85.63% (3332/3891)
• Functions: 96.41% (1588/1647)
• Lines: 95.60% (5005/5235)
• Test files: 116 passed
• Tests: 607 passed
• 기준 commit: 9571ef5 test: raise TypeScript branch coverage

Refactor-First Coverage Checklist

• Characterization tests: 과밀지점 리팩터링 전 public behavior를 먼저 고정하고 해당 단위 test green을 기록한다.
• Hotspot refactor: reviews.ts review read flow의 반복 조립을 domain-local read context helper로 추출한다.
• Hotspot refactor: useNaverFestivalMarkers의 marker lifecycle과 selection style update를 local planner/controller seam으로 분리한다.
• Hotspot refactor: useAppReviewCrudActions의 API 이후 collection/cache/my-page 갱신을 pure helper로 분리한다.
• Hotspot refactor: festival-domain read/import policy의 source 없음, empty items, stale cleanup, date/window branch를 service boundary로 고정한다.
• Hotspot refactor: numeric-literal-audit와 event normalize script의 IO와 pure classification/compare logic을 분리한다.
• Coverage fill: base-data-mappers, festival-series, simple mapper/component branch는 리팩터링 없이 테스트 추가로 처리한다.
• Final hard gate: Vitest coverage threshold를 statements/branches/functions/lines 95로 설정하고 npm.cmd run test:coverage:ts가 실제 threshold 기준으로 통과하게 고정한다.

Coverage Slice Checklist

• src/hooks coverage slice: app navigation, review/comment action, feedback/bootstrap effect, route query branch를 public hook/helper 기준으로 테스트하고 coverage summary를 기록한다.
• src/components/naver-map coverage slice: marker sync, selection sync, viewport sync, overlay fallback을 SDK local mock boundary로 테스트하고 coverage summary를 기록한다.
• src/api coverage slice: API core cache/error/body parsing, reviews client 실패/성공 branch, bootstrap/tourism edge response를 테스트하고 coverage summary를 기록한다.
• Worker service coverage slice: auth/session/social-user, notification/review handlers, festival/tourism read-service/repository, route handler branch를 Request/Response boundary로 테스트하고 coverage summary를 기록한다.
• Final hard gate slice: Vitest coverage threshold를 statements/branches/functions/lines 95로 설정하고 npm.cmd run test:coverage:ts가 실제 threshold 기준으로 통과하게 고정한다.

구현 순서

Order	Issue	Intent	Completion evidence
1	#328	coverage summary에서 미달 파일과 branch를 선별	coverage output
2	#328	public behavior/stable boundary 테스트 추가	PR diff
3	#328	Vitest threshold 95% hard gate 설정	config diff
4	#328	로컬 검증과 PR/CI/merge 근거 기록	validation output, PR URL, CI URL, merge SHA

Behavior Preservation Rules

• 리팩터링 전 characterization test를 먼저 추가한다.
• 기존 public exports, hook return shape, Worker endpoint, response shape, API client behavior는 유지한다.
• 사용자-facing copy, mojibake 문자열, DB schema, OAuth 경로, route path는 변경하지 않는다.
• private 구현에 맞춘 monkey patch는 금지한다.
• coverage exclude 확대, denominator 줄이기, import-only test는 금지한다.
• 새 helper는 owner module 근처에 둔다. global barrel이나 중앙 type 덩어리로 회귀하지 않는다.

Test Gate

Coverage hard gate 변경이므로 최소 check:numeric-literals, lint, typecheck, test:unit, test:integration, test:regression, test:e2e, test:coverage:ts, build, git diff --check, UTF-8 integrity check가 필요하다.

Completion Evidence

• Scope-ID and required report metadata
• PR link
• Commit SHA
• Test command outputs
• CI links
• Main merge commit SHA
• TSK-009-05 TypeScript coverage 95 #328 checklist evidence
• Parent TSK-009-00 Epic: UI/UX expectation tracking and 95% coverage gate #323 checklist linkage

Handoff Checklist

• I am on the correct branch: typescript-coverage-95.
• I have read the relevant repository instructions.
• I know the parent issue and sub-issue.
• I know what must not change.
• I know the simplest acceptable implementation path.
• I know which files or boundaries I must not touch.
• I know what evidence is required before completion.
• I will stop if the task crosses an out-of-scope boundary.

Canonical Skill / Policy Source

• llm-code-generation-protocol
• tdd
• Repository AGENTS.md
• Agent governance parent/child/checklist policy

Verification Contract

required commands: npm.cmd run check:numeric-literals; npm.cmd run lint; npm.cmd run typecheck; npm.cmd run test:unit; npm.cmd run test:integration; npm.cmd run test:regression; npm.cmd run test:e2e; npm.cmd run test:coverage:ts; npm.cmd run build; git diff --check; UTF-8 integrity check.

source-of-truth readback: #328 issue checklist, #323 parent checklist, PR diff/body, GitHub Actions checks, changed test/config readback, coverage summary readback.

required evidence: PR URL, main merge SHA, CI/CodeQL result links, local validation command results, coverage summary showing statements/branches/functions/lines >= 95%, UTF-8 readback result.

fail-closed failure modes: parent/child checklist missing; any coverage metric below 95%; threshold passes by widening exclude scope instead of adding meaningful tests; API/DB/OAuth contract change required; user-facing copy scope exceeded; UTF-8 or Markdown structure corruption.

[ClarusIubar]

TSK-009-05 시작 전 최신 TypeScript coverage snapshot입니다.

• 기준 명령: npm.cmd run test:coverage:ts
• Statements: 33.01%
• Branches: 28.16%
• Functions: 30.63%
• Lines: 34.20%

이 이슈는 아직 완료 조건을 충족하지 않습니다. 95% hard gate를 켜기 전, Worker service/domain, React components/hooks, API clients, scripts의 미커버 영역을 실제 behavior test로 채워야 합니다.

[ClarusIubar]

TSK-009-05 중간 진행 evidence

• Scope-ID: TSK-009-05
• Issue: TSK-009-05 TypeScript coverage 95 #328
• Parent Issue: TSK-009-00 Epic: UI/UX expectation tracking and 95% coverage gate #323
• Branch: typescript-coverage-95
• Status: partial

Architecture Boundary Gate

• Responsibility map: 테스트만 보강했으며 production behavior, 사용자-facing copy, API shape, DB schema, OAuth 경로는 변경하지 않았습니다.
• Dependency direction: 테스트는 public hook/helper, component boundary, API/script/Worker request-response boundary에만 의존합니다.
• Test seam: Naver SDK mock, browser API mock, fetch/Response boundary, script entrypoint import boundary를 사용했습니다.
• Scope map: #328의 src/hooks, src/components/naver-map, src/api, Worker service, script boundary coverage slice에 대응합니다.
• Architecture risk: branch coverage가 아직 낮아 95 hard gate는 미달입니다. threshold를 95로 올리면 현재 실패하므로 아직 설정하지 않았습니다.

이번 추가 보강

• src/components/naver-map: useNaverViewportSync readiness, debounce, cleanup, listener removal 분기 추가 검증.
• scripts: upload-sample-place-images 설정 누락과 storage upload failure path 추가 검증.
• src/hooks/app-navigation: shell back handler의 return view, comment sheet, route preview, browser history 우선순위 추가 검증.

검증 결과

• npm.cmd exec vitest -- run test/unit/naver-map-hooks.test.tsx: 통과, 10 tests.
• npm.cmd exec vitest -- run test/unit/script-entrypoints.test.ts: 통과, 9 tests.
• npm.cmd exec vitest -- run test/unit/navigation-route-loaders.test.tsx: 통과, 17 tests.
• npm.cmd run test:coverage:ts: 통과.
  • Statements: 92.65% (5257/5674)
  • Branches: 76.86% (2991/3891)
  • Functions: 95.20% (1568/1647)
  • Lines: 92.76% (4856/5235)
  • Test files: 104 passed
  • Tests: 503 passed
• npm.cmd run typecheck: 통과.
• git diff --check: 통과. Windows LF -> CRLF warning only.

남은 작업

• Final hard gate는 아직 미달이라 체크하지 않습니다.
• 다음 우선순위는 branch gap이 큰 Worker auth/session/social-user, review/notification handlers, script normalize/derive, notification/page-stage/review component branch입니다.

[ClarusIubar]

Coverage progress checkpoint

Branch: typescript-coverage-95
Commit: f04571c

Refactor-first slices completed

• Worker review read flow: extracted review-domain/read-context.ts so review handlers no longer repeat comment/like/stamp/user/route fan-out assembly.
• Naver festival markers: extracted local festivalMarkerController.ts so the hook keeps lifecycle ownership while SDK marker creation/selection mutation is directly testable.
• Review CRUD collections: extracted reviewCrudCollectionUpdates.ts so my-page/cache mutation rules are covered as pure behavior.
• Festival read/import services: added repository-mocked service tests for no-source, stale cleanup, metadata fallback, window/area filtering, and banner readiness.
• Numeric audit/OAuth/base-data/script edge tests: added public behavior tests without widening coverage excludes.

Local validation

• npm.cmd run check:numeric-literals: pass
• npm.cmd run lint: pass
• npm.cmd run typecheck: pass
• npm.cmd run test:unit: pass
• npm.cmd run test:coverage:ts: pass
• npm.cmd run build: pass
• git diff --check: pass
• UTF-8 integrity check: pass during commit hook

Current TypeScript coverage

• Statements: 95.78% (5413/5651)
• Branches: 86.66% (3353/3869)
• Functions: 96.71% (1588/1642)
• Lines: 95.98% (5018/5228)

Remaining branch hotspots

• scripts/daejeon-event-sync/normalize.ts
• deploy/api-worker-shell/runtime/base-data-mappers.ts
• deploy/api-worker-shell/services/community-domain/mapper.ts
• deploy/api-worker-shell/services/stamp-domain/repository.ts
• src/hooks/app-* navigation/bootstrap/data state helpers
• src/components small conditional render branches

This is not the final 95% branch gate yet. It is a green checkpoint that keeps the refactor-first approach moving without changing API shape, DB schema, OAuth flow, or user-facing copy.

[ClarusIubar]

Coverage checkpoint

• Branch: typescript-coverage-95
• Commit: 52672fb
• Coverage command: npm.cmd run test:coverage:ts
• Coverage result:
  • Statements: 95.89% (5419/5651)
  • Branches: 87.07% (3369/3869)
  • Functions: 96.77% (1589/1642)
  • Lines: 96.07% (5023/5228)

이번 slice 근거

• reviewCrudCollectionUpdates는 hook root file count 회귀를 피하기 위해 src/lib pure helper로 이동했습니다.
• auth/social-user, community mapper, API pending cache invalidation, geolocation watcher/error mapping, AdminPanel busy/null 상태를 public behavior 기준으로 보강했습니다.
• numeric literal baseline은 새 src/lib/reviewCrudCollectionUpdates.ts 경로로 명시 분류했습니다.

통과한 로컬 검증

• npm.cmd run check:numeric-literals
• npm.cmd run lint
• npm.cmd run typecheck
• npm.cmd run test:unit
• npm.cmd run test:coverage:ts
• npm.cmd run build
• git diff --check
• commit hook UTF-8 integrity check

남은 gap

• Branches는 86.66% -> 87.07%까지 상승했지만 95% hard gate까지는 아직 미달입니다.
• 다음 우선순위는 missed branch 수 기준 normalize.ts, festival-series.ts, base-data-mappers.ts, EventTabTourismSection.tsx, useFloatingBackButton.ts, shellBackNavigation.ts, Worker stamps/community-routes/review-domain입니다.