Files
clean-architecture-frontend…/docs/adr/VD-01-typescript-lint-tooling.md
DongHyeonka 75fad73a7d docs(records): 기록·설계서·결정 기록 67개에 한국어 머리 블록을 단다
문제: 옮긴 기록은 지금 동작을 설명하는지, 상태가 무엇인지, 지금
정본이 어디인지 알 길이 없다. 설계서·계획서 27개와 docs/architecture
목표 설계 16개에는 상태 칸이 없고, VD는 「상태: Accepted」 같은 영어
값을 쓴다.

고른 방법: docs-system.md 4절 형식으로 맨 위에 머리 블록을 달고 본문은
한 글자도 고치지 않는다. 상태는 기계 변환이다.
- 설계서: Accepted·확정·정본·설계 완료 → 채택, 상태 줄이 없으면
  확인 안 함 (채택 4, 확인 안 함 21)
- 계획서: 체크 상자가 모두 표시됐으면 끝남, 아니면 확인 안 함. SPEC.md는
  같은 폴더 plan.md와 같은 근거(0.2.0으로 끝난 라운드)로 끝남 (끝남 5,
  확인 안 함 14. 이미 블록이 있던 5개는 그대로)
- 결정 기록: Accepted → 채택, 날짜가 붙은 뒤늦은 보완 메모가 본문에
  있으면 채택(보완) (채택 14, 채택(보완) 9). 프론트 VD는 처음부터
  한국어로 썼고 번역하지 않으므로 둘째 줄은 「원문이다」 문구다.
- 작성일: 파일 이름 날짜 → 본문 날짜 줄(VD는 `결정일:`) → git 첫 추가일.

위험: VD-09·11·13은 git으로 보면 결정 뒤 본문이 그 자리에서
고쳐졌지만 본문에 날짜 표시가 없어 기계 규칙대로 채택으로 두었다.
보완으로 올릴지는 사람이 정한다. 「현재 정본」은 지금 있는 살아 있는
문서나 코드 경로만 쓴다.

검증: 블록과 그 뒤 빈 줄 하나를 빼면 72개 모두 `git show HEAD:`와 바이트가
같다. 뒤 커밋의 문서 검사 head 규칙으로 돌려 문제 0건.
2026-11-08 17:25:41 +09:00

4.3 KiB

결정 기록 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 채택(보완)
  • 작성일: 2026-07-26
  • 요약: TypeScript 7과 ESLint 10으로 옮길 때 컴파일러와 운영 소스를 한꺼번에 바꾸지 않고 JS·TS 파일이 같은 품질 게이트를 통과하게 하는 도구 구성을 정한 결정이다.
  • 현재 정본: eslint.config.ts, tsconfig.json, scripts/check-architecture.ts

VD-01: TypeScript 7과 ESLint 10의 점진적 전환 도구

  • 상태: Accepted
  • 결정일: 2026-07-26
  • 적용 브랜치: feature-frontend-typescript-tooling-foundation

배경

저장소는 TypeScript 7.0.2와 ESLint 10.8.0을 고정하고 있다. 첫 전환 브랜치는 compiler를 변경하거나 production source를 일괄 변환하지 않고 JS/JSX/TS/TSX가 같은 품질 게이트를 통과하게 해야 한다.

결정 시점의 package peer contract는 다음과 같다.

  • typescript-eslint@8.65.0과 canary는 TypeScript <6.1.0을 요구한다.
  • eslint-plugin-jsx-a11y@6.10.2는 ESLint <=9를 요구한다.
  • eslint-plugin-react-hooks@7.1.1은 ESLint 10을 지원한다.
  • Babel 8 ESLint parser는 ESLint 10을 지원하고 Node >=24.11.0을 요구한다.

호환되지 않는 peer dependency를 강제 설치하면 lockfile 검증은 통과하더라도 지원되지 않는 parser와 rule 조합을 플랫폼 계약으로 만들게 된다.

결정

  1. TypeScript 7.0.2와 ESLint 10.8.0을 유지한다.
  2. TypeScript/TSX의 ESLint syntax parsing에는 @babel/eslint-parser와 TypeScript/JSX syntax plugin을 사용한다.
  3. TypeScript의 이름 해석, unused 진단과 type semantics는 tsc가 소유한다. Babel parser가 TypeScript scope manager를 제공하지 않으므로 TS 파일의 core no-undef와 no-unused-vars는 끄고 분리된 app/node/test TypeScript project를 필수 게이트로 실행한다.
  4. React Hook 규칙은 호환되는 eslint-plugin-react-hooks로 즉시 적용한다.
  5. JSX 접근성은 현재의 semantic component contract, Testing Library, axe 기반 cross-browser gate와 수동 검토 계약이 계속 담당한다. 호환되지 않는 eslint-plugin-jsx-a11y는 설치하지 않는다.
  6. Babel 8의 지원 범위에 맞춰 Node engine 하한을 24.11.0으로 명시한다.
  7. production source의 대량 rename은 이 결정에 포함하지 않는다.

적용 후 상태 (2026-07-27)

후속 migration에서 production source, 비-fixture tests, Node scripts와 지원되는 tool config를 모두 TS/TSX로 전환했다. allowJs는 껐고 runtime/source 영역의 JavaScript 재유입은 architecture gate가 거절한다. Node scripts는 pinned Node 24에서 .ts로 직접 실행되며 NodeNext, verbatimModuleSyntax와 erasableSyntaxOnly로 별도 typecheck한다. tests/fixtures/**도 TS/TSX architecture/security/type negative input으로 전환했다. 이는 7번 결정의 범위를 변경한 것이 아니라 그 기반 위에서 완료한 별도 후속 작업이다.

검증

  • check:types는 app, Node scripts/config, tests project를 모두 검사한다.
  • TS invalid-call, invalid port, discriminated-union fixture는 실패해야 한다.
  • ESLint와 check:architecture의 import 그래프(scripts/check-architecture.ts)가 TS/TSX architecture fixture를 검사한다. dependency-cruiser 18은 TypeScript 7을 해석하지 못해 0개 모듈을 검사하고 통과했으므로 실행하지 않는다(리뷰 12-05). .dependency-cruiser.json은 이름만 남은 규칙 파일이고 그래프가 읽는다.
  • registry scanner는 TS registry의 required field, uniqueness와 reference를 검증한다.
  • browser security gate는 TSX의 금지된 raw HTML fixture를 거절한다.

후속 검토와 제거

typescript-eslint가 TypeScript 7을, JSX 접근성 plugin이 ESLint 10을 공식 지원하면 별도 dependency 브랜치에서 peer metadata와 전체 negative fixture를 재검증한다. 교체할 때는 Babel parser package와 TS 전용 ESLint override를 함께 제거한다. compiler downgrade나 --force 설치는 이 ADR의 rollback 방법이 아니다.