Barbelic devdocs

Appearance

ESLint React Hook Gate ​

이 문서는 Barbelic의 React 코드에서 ESLint와 React Hooks 검사를 점진적으로 복구하는 기준을 고정한다. 첫 단계의 대상은 모바일과 데스크톱을 모두 포함한 src/react/**/*.{ts,tsx}다.

명령 ​

bash
npm run lint
npm run check:lint
  • npm run lint는 현재 결과를 사람이 읽을 수 있게 출력한다.
  • npm run check:lint는 신규 오류, 신규 hook dependency 경고, 무단 suppression을 차단하는 CI gate다.
  • 기본 npm run check가 check:lint를 실행하므로 기존 GitHub Actions workflow에도 별도 우회 없이 적용된다.

현재 정책 ​

  • react-hooks/rules-of-hooks는 모든 React 소스에서 error다.
  • react-hooks/exhaustive-deps는 새로 깨끗한 파일에서 error다.
  • 기존 dependency 부채가 있는 파일만 warning으로 낮추되, eslint-baseline.json이 파일명과 정확한 ESLint 메시지를 함께 고정한다.
  • 기존 경고와 같은 파일에서 다른 경고로 바꿔치기해도 fingerprint가 달라져 실패한다.
  • 기존 경고를 해결했을 때도 baseline을 같은 PR에서 줄이지 않으면 실패한다.
  • eslint-disable-line과 eslint-disable-next-line만 허용한다. 규칙 이름과 -- 이유가 반드시 있어야 하며, 승인된 suppression 자체도 baseline으로 고정한다.
  • 파일 전체 eslint-disable은 허용하지 않는다.

부채를 줄이는 방법 ​

  1. dependency 문제를 동작 의미에 맞게 수정한다.
  2. npm run check:lint를 실행해 사라진 fingerprint를 확인한다.
  3. eslint-baseline.json에서 해당 메시지를 제거한다.
  4. 그 파일의 마지막 경고였다면 eslint.config.mjs의 legacy 파일 목록에서도 제거한다.
  5. npm run check와 npm run build를 실행한다.

baseline은 기존 부채를 허용하기 위한 상한선이지 새 예외를 추가하는 목록이 아니다. 새 경고를 baseline에 넣는 변경은 원칙적으로 허용하지 않는다.

다음 단계 ​

이번 단계는 React hook correctness에 집중한다. noUnusedLocals와 noUnusedParameters는 현재 진단량을 별도 fingerprint로 고정한 뒤 CI 전용 gate로 추가한다. Vite, API, scripts, tests 같은 Node JavaScript lint도 React gate가 안정화된 뒤 별도 설정으로 추가한다. 이렇게 해야 기존 부채 때문에 핵심 hook 검사가 다시 꺼지는 일을 피할 수 있다.

설정 형식은 ESLint flat config를, hook 규칙의 의미는 React Hooks lint 문서를 따른다.