린트 규칙 리뷰 스킬

ESLint 규칙 리뷰 스킬

수천 개의 리뷰 코멘트를 남긴 유지보수자의 방식으로 린트 규칙을 리뷰합니다. 그 유지보수자의 핵심 습관은 경험적(empirical)입니다. 단순히 규칙을 읽지 않고, 그것을 깨뜨리려고 시도합니다. 조건을 삭제하고 테스트가 실패하는지 확인하며, 아무도 생각하지 못한 신택스를 발명합니다. 여기서도 그 습관을 따릅니다. 실패하는 테스트나 생존한 변이(mutant)로 뒷받침된 발견은 그럴듯해 보이는 발견보다 훨씬 가치가 있으며, 그럴듯한 노이즈는 자동화된 리뷰가 무시되는 이유입니다.

발견 사항은 사용자에게 전달되며, 사용자가 어떻게 처리할지 결정합니다. 리뷰를 로컬 파일에 작성하는 것이 전부입니다. GitHub에 게시하거나 푸시하는 것은 사용자가 별도로 요청할 때만 발생합니다.

1. 변경 사항 이해

리뷰 대상이 무엇인지 파악합니다: PR, 브랜치, 또는 규칙 파일. PR의 경우, 이후 단계에서 코드를 실행해야 하므로 가능하면 헤드 커밋(head commit)을 체크아웃합니다.

의견을 형성하기 전에 다음을 읽습니다:

• 규칙, 테스트, 문서 페이지
• PR 설명과 연결된 이슈. 규칙은 자체 알고리즘이 아니라 목적에 따라 평가되기 때문입니다.
• 동일 저장소의 두세 개 관련 규칙과 CONTRIBUTING 문서

설명에서 작성자가 한 질문을 기록합니다. 리뷰는 그 질문에 답해야 합니다.

저장소의 관례가 이 스킬의 참조(references)보다 우선합니다. 참조는 여러 프로젝트에서 가져온 것이므로, 패턴이 저장소의 명확한 관례와 충돌하면 저장소를 따릅니다.

참조는 방대하므로 처음부터 끝까지 읽지 마십시오. references/index.md에서 시작하여 각 패턴을 나열하고, 이 변경 사항에 해당하는 섹션만 가져옵니다. 또한 references/extra-checks.md를 읽습니다. 이는 짧으며 도구 함정과 fixer, import 규칙, Flint에 대한 검사를 다룹니다.

2. 규칙의 설계 확인

변경 유형에 따라 인덱스의 design.md 목록에서 선택합니다:

• 새 규칙: 규칙이 속하는지, 범위, 다른 규칙과의 중복, 타입 정보, 옵션, 프리셋 위치.
• 기존 규칙 변경: semver 영향, 동일한 변경이 필요한 관련 규칙, 변경이 이슈에 부합하는지. 나머지는 건너뜁니다.

PR이 초기 상태인 경우(예: 테스트가 없거나 설계 재고가 필요한 경우), 상위 수준 리뷰에서 멈추고 그렇게 말한 후, 변이(mutation)를 건너뜁니다. 테스트 없이는 유용한 정보를 줄 수 없기 때문입니다. 그래도 몇 가지 케이스에 대해 규칙을 시도해 보십시오. 실제 버그는 어떤 단계에서도 보고할 가치가 있습니다. 변경될 코드에 대한 상세한 코멘트는 모두의 시간을 낭비합니다.

3. 추가된 모든 라인 읽기

인덱스를 사용하여 변경된 내용에 해당하는 섹션을 가져옵니다:

변경 사항	확인할 사항
규칙 로직	bugs.md, simplification.md, performance.md
수정자(Fixer) 또는 제안(Suggestion)	fixes.md
메시지	messages.md
테스트	test-method.md
문서 페이지	docs.md
새 이름, 옵션, 또는 규칙	naming.md

이 작업은 버그를 찾으려고 시도하기 전에 수행합니다. 버그 사냥이 시작되면 그것이 우선시되기 때문입니다. 진행하면서 메모를 하고, 5단계에서 정리합니다.

diff에서 추가된 각 라인을 하나씩 살펴보며 각각에 대해 다음을 질문합니다:

• 이름: 더 읽지 않고도 이 식별자가 무엇을 담거나 하는지 알 수 있습니까? 타입보다 목적을 설명하는 이름, 그리고 잘못된 동작을 주장하는 이름을 주의하십시오. 이해하는 데 두 번 읽어야 했다면, 그렇게 말하고 더 나은 이름을 제안하십시오.
• 로컬 변수: 이 변수가 설정된 직후 한 번만 사용됩니까? 인라인화(inlining)를 제안하십시오.
• 조건: 축소될 수 있습니까? !x || x.kind !== y는 x?.kind !== y가 됩니다. 중첩되거나 인접한 if는 종종 병합될 수 있으며, 불리언 if는 종종 직접 반환할 수 있습니다.
• 가드(Guard): AST와 위의 코드를 고려할 때 이 상태가 실제로 발생할 수 있습니까?
• 재사용: 공유 유틸리티가 이미 이 작업을 수행합니까? 어떤 헬퍼든 받아들이기 전에 확인하십시오. 헬퍼가 create 내부에 있다면 더 적은 매개변수가 필요할까요?
• 길이: 동일한 작업을 수행하는 더 적은 코드가 있습니까? 단순화는 과거 리뷰에서 가장 큰 범주입니다.
• 할 가치가 있는가: 이 코드나 TODO가 아무도 필요로 하지 않는 것을 계획하고 있습니까? 제거해도 된다고 말하십시오.

코드가 AI 지원처럼 보인다면 더 비판적인 눈으로 읽으십시오. 그곳이 패딩(padding)이 모이는 곳이기 때문입니다.

모든 주석과 문서 문장을 훑어보십시오. 버그 사냥이 이것을 압도하지만, 실제 리뷰 코멘트의 일반적인 출처이므로 추가된 각 주석과 각 문서 라인을 별도의 패스로 수행하십시오. 올바른지 묻지 말고, 작성된 대로 거기에 있어야 하는지 물으십시오:

• 이 주석이 오래되어 의미가 없어질까요? 테스트 커버리지, 이력, 또는 테스트가 무엇을 커버하는지에 대한 메모는 그렇습니다. 삭제를 제안하십시오.
• 코드를 다시 설명합니까? 삭제를 제안하십시오.
• 업스트림 코드의 포크와 같은 중요한 알려진 단축키입니까? TODO와 가능하면 이슈 링크를 요청하고 정확한 주석을 제안하십시오.
• 최종 사용자가 이 문서 문장에 관심을 가질까요? 구현 세부 사항은 페이지에 속하지 않습니다.
• 이 문서 예제에 필요하지 않은 코드가 포함되어 있습니까? 동작을 보여주는 것 이상을 제거할 것을 제안하십시오.
• 문장이 정확합니까? 보편적이거나 항상 사실인 것처럼 들리지만 그렇지 않은 표현을 주의하고, 다시 쓰기를 제안하십시오.

이것들을 ```suggestion 블록으로 제공하십시오. 작성자가 수락하기 쉽습니다.

좋은 점을 언급하십시오. 리뷰에 도움이 되었거나 까다로운 것을 처리한 점을 주목하고, 리뷰 본문이나 [Praise] 코멘트로 구체적으로 언급하십시오.

4. 깨뜨리려고 시도하기

이 단계는 가장 가치 있는 발견을 생성하므로 건너뛰지 마십시오. 먼저 규칙의 기존 테스트가 통과하는지 확인하여, 이 규칙의 테스트만 실행하는 작업 명령어를 확보합니다.

조건을 변이(mutate)시킵니다. 저장소 루트에서 번들 스크립트를 실행합니다. Node 22.18 이상이 필요하며, 이는 저장소가 고정한 버전과 다를 수 있습니다. 각 변이(mutant)는 하나의 테스트 실행이므로, 백그라운드에서 실행하십시오. 변이는 규칙 파일을 제자리에서 편집하므로, 그 사이에 실행하는 다른 모든 작업은 임시 이름으로 저장된 규칙의 복사본을 사용해야 합니다:

node <skill-dir>/scripts/mutate-conditions.ts --file <rule> --test "<test command>" --base <base ref>

--base는 변이를 PR이 변경한 라인으로 제한하고, --diff <file>은 diff로 동일한 작업을 수행합니다. 전체 새 규칙을 변이하려면 둘 다 생략하십시오. 변이(mutant)는 소스 순서대로 최대 --max(기본 60)까지 실행되므로, 요약에 테스트되지 않은 것이 보이면 값을 높이십시오. 테스트가 패키지 폴더에서 실행되는 경우, 거기서 스크립트를 실행하십시오. --out <file>은 전체 결과를 저장하고, 생존자 목록은 항상 마지막에 인쇄됩니다. 먼저 스크립트는 규칙이 에러를 던질 때 테스트가 실패하는지 확인하고, 그렇지 않으면 중단됩니다. 테스트가 규칙을 실행하지 않기 때문입니다. 스크립트는 완료되거나 중단될 때 파일을 복원합니다. 직접 종료된 경우, 다음 실행이 시작을 거부하고 원본이 저장된 위치를 인쇄하므로, 규칙을 변경하기 전에 두 파일을 비교하십시오. 그 사이에 편집했을 수 있기 때문입니다. 테스트 명령어가 규칙을 빌드하는 경우, 다시 빌드하십시오. 빌드 출력에는 마지막 변이(mutant)가 여전히 포함되어 있기 때문입니다. 스크립트는 저장소의 typescript로 파싱하며, TypeScript 7 이상에서는 --typescript로 이전 복사본을 전달하는 방법을 인쇄합니다.

테스트가 감지하지 못한 변이(mutant)는 생존자(survivor)입니다. 각각은 테스트가 누락되었거나 코드가 죽은 코드임을 의미하며, 어느 쪽인지 파악해야 합니다. 조건을 삭제하고 어떤 입력이 필요할지 생각해 보십시오. 구성할 수 없으면 코드 삭제를 권장합니다. 구성할 수 있으면 다음 단계에 추가하십시오. likelyTypeOnly로 표시된 생존자는 종종 컴파일러를 위해서만 존재하는 기본 null-check 종료문이므로, 마지막에 확인하되 해당 분기가 단순히 테스트되지 않은 것은 아닌지 확인하십시오. 테스트 러너가 타입 검사를 수행하는 경우, 변이(mutant)가 컴파일되지 않아서 "실패"할 수도 있으므로, 가능하면 트랜스파일 전용 명령어를 사용하십시오.

스크립트는 일반적인 변이만 다룹니다. 스크립트가 도달할 수 없지만 PR이 의존하는 것, 예를 들어 인수를 범위 내의 유사한 변수로 바꾸는 것도 직접 시도해 보십시오.

헤드와 베이스 비교하기. 기존 규칙의 변경의 경우 이것이 가장 중요한 검사입니다. 이전에 작동하던 코드의 회귀는 이미 존재했던 격차보다 훨씬 중요하며, 두 버전을 모두 실행하지 않고는 구분할 수 없습니다. 베이스 버전을 규칙 옆에 저장합니다. 예를 들어 git show <base>:./<rule> > <rule-dir>/<name>.base-tmp.ts를 사용하거나 diff를 역적용하여 저장합니다. 그런 다음 assets/compare-rule.test.ts를 규칙의 테스트 옆에 복사하고 표시된 라인을 조정합니다. 각 케이스를 보고서 수를 비교하여 정렬하며, 각 픽스처에서 메시지, 범위, 수정 출력, 제안, 충돌, 컴파일 오류도 기록합니다. CHANGED OUTPUT 결과는 직접 읽으십시오. 변경된 메시지나 수정이 버그일 수 있으며, fixtureErrors가 있는 케이스는 해당 픽스처가 컴파일될 때까지 무시하십시오. 수정자를 추가하는 PR의 경우, 수정 및 제안 출력이 주요 읽을거리이므로 해당 케이스에 expectedOutput을 설정하십시오. PR이 옵션을 추가하는 경우, baseOptions를 설정하여 베이스 버전의 스키마가 케이스를 수락하도록 하십시오. 그렇지 않으면 케이스는 헤드에서만 판단됩니다.

새 규칙의 경우, head와 base 모두로 가져와서, 하네스가 버전을 비교하는 대신 ok 또는 WRONG을 보고하도록 합니다. 하네스가 플러그인에 맞지 않으면, 대신 저장소 자체 테스트 하네스에서 임시 테스트 파일을 사용하십시오.

적대적 테스트 케이스 작성하기. references/test-cases.md에서 이 규칙이 다루는 구문과 타입에 맞는 범주를 선택하고, 문자 그대로의 케이스를 작성하십시오. 각 케이스를 실행하기 전에 올바른 동작을 결정하십시오. 그래야 결과가 무엇이든 합리화하는 것을 막을 수 있습니다. 보고서 수뿐만 아니라 메시지 데이터도 인쇄하십시오. 메시지의 잘못된 타입 이름도 버그이기 때문입니다. 새 구문의 케이스를 이전 구문의 제어 케이스와 짝지으십시오. 예를 들어 심볼 키와 같은 케이스를 문자열 키로 사용하는 경우. 다음을 찾으십시오:

• 충돌
• 거짓 양성(False positive): 유효한 코드가 보고됨
• 거짓 음성(False negative): 유효하지 않은 코드가 보고되지 않음
• 유효하지 않은 코드를 생성하거나, 동작을 변경하거나, 주석을 삭제하는 수정
• 오류 코드보다 더 넓은 보고 범위

무언가를 발견한 케이스는 리뷰에 리터럴 테스트 케이스로 포함될 수 있도록 보관하십시오. 리터럴이 중요합니다. 이 유지보수자는 직접 작성한 케이스를 요청하고 .map, 팩토리, 생성된 테스트를 반대합니다.

큰 제안 증명하기. 재설계가 여러 버그를 제거할 것이라고 생각되면, 프로토타입을 만들고 기존 테스트를 실행하십시오. "268개 중 267개 테스트 통과, 나머지 하나가 실패하는 이유는 다음과 같습니다"는 직감보다 훨씬 유용합니다.

정리하기. git status를 실행하고 다음으로 넘어가기 전에 모든 임시 파일을 제거하여 저장소를 원래 상태로 되돌립니다.

5. 발견 사항 필터링

무언가를 작성하기 전에 각 발견 사항을 검토합니다:

• 버그: 케이스와 실제로 발생한 상황을 포함하십시오. 재현할 수 없다면 제거하거나, 특별히 의심할 이유가 있다면 [Question]으로 낮추십시오.
• 순서: 회귀가 먼저, 그 다음 새 코드의 버그, 그 다음 PR이 건드리는 기존 버그 순서입니다.
• 하나의 근본 원인: 재설계가 여러 버그를 고칠 수 있다면, 하나의 코멘트로 만들고 그 안에 케이스들을 나열하십시오. 버그가 자체적인 수정이 필요한 경우(예: 회귀)에만 별도의 코멘트를 유지하십시오.
• 논쟁의 여지가 있는 위치: 이것들은 차단하지 않는 질문으로 취급하십시오: 노드의 in 검사, esquery 사용, 옵션 스키마 모양, import ts 스타일. 다른 유지보수자들이 합리적으로 이견을 제시한 사항입니다.
• 확장 또는 연기: 격차가 규칙과 동일한 개념이고 실제 사용자가 겪을 것 같다면, 이 PR에서 요청하십시오. 그렇지 않으면 후속 이슈를 제안하십시오.
• 옵션 추가 또는 제거: 규칙이 유효한 코드를 금지하거나 실제 사용자가 요청한 경우에만 옵션을 요청하십시오.
• 기존 코드: PR이 건드리지 않은 문제는 심각하지 않으면 생략하고, [Non-Actionable]로 표시하십시오.
• 중복: 반복을 하나의 코멘트로 병합하고 "여기 및 다른 곳"이라고 말하십시오.

노이즈는 누락보다 비용이 더 큽니다. 세 개의 약한 코멘트를 빠르게 훑어보는 작성자는 실제 코멘트도 훑어볼 것입니다. 차단 코멘트는 병합 전에 반드시 변경되어야 하는 것만 포함해야 합니다. 최대 약 8개의 비차단 코멘트를 유지하고, 코드를 가장 개선하는 것을 선택하되, 변경을 요청하는 곳에는 적용 가능한 제안을 함께 제공하십시오. 다음을 먼저 제거하십시오:

• 명확성에 실제 이득이 없는 취향의 문제(예: 메시지 재구성, 괜찮은 조건문 축소)
• 설명이 의도적이라고 말하는 것(예: 계획된 작업을 위한 스캐폴딩)
• 실제 사례를 찾을 수 없었고 특별히 의심할 이유도 남지 않은 버그
• 공백 및 따옴표 스타일
• 아무것도 추가하지 않는 프로세스 요청(예: 모든 작은 TODO에 대한 추적 이슈)

보고할 것이 없다는 것은 좋은 결과이므로, 철저해 보이기 위해 발견 사항을 만들어 내지 마십시오.

평결을 차단 코멘트와 일치시키십시오. 차단하는 것이 없으면 승인하고 나머지는 제안으로 남겨 두십시오. 견고한 PR에 대한 이 유지보수자의 많은 리뷰는 하나 또는 두 개의 작은 요청이 있는 따뜻한 승인입니다.

6. 리뷰 작성

references/review-voice.md를 읽은 다음, 현재 디렉토리에 lint-rule-review-skill-<pr-or-rule>.md를 작성하되, 커밋하지 마십시오. 리뷰 본문은 몇 문장으로 유지하고, 작성자의 질문에 답하거나 설계 결정을 설명할 때만 길게 작성하십시오. 다음 구조를 사용하십시오:

# <PR 또는 규칙> 리뷰

**평결:** 승인 | 변경 요청 | 상위 수준만

<리뷰 본문, review-voice.md의 순서를 따름>

## 인라인 코멘트

### `path/to/file.ts:42` · 차단

[Bug] <게시될 코멘트>

```ts
<리터럴 실패 케이스 또는 제안>
```

증거: <실행한 것과 결과, 또는 "재현되지 않음">

## 확인되지 않음

<실행하거나 확인할 수 없었던 것과 그 이유>

각 코멘트를 blocking 또는 non-blocking으로 표시하고, 차단 코멘트를 먼저 정렬합니다. "증거"는 사용자를 위한 것이며 게시되지 않습니다.