타입 인식 린트
타입 인식 린트는 타입스크립트의 타입 시스템에 의존하는 규칙을 가능하게 합니다. 예를 들어, 처리되지 않은 프로미스 또는 안전하지 않은 할당을 탐지할 수 있습니다. 옥린트에서는 tsgolint를 통해 타입 인식 린트 기능을 제공하며, 이는 옥린트 CLI와 구성 시스템에 통합되어 있습니다.
이 기능은 현재 알파 단계입니다. 규칙 커버리지, 성능 및 호환성은 계속 개선되고 있습니다.
개요
옥린트는 두 가지 구성 요소 간의 책임을 분리합니다:
옥린트 (러스트) 파일 탐색, 무시 로직, 구성, 타입 인식이 없는 규칙 및 보고를 처리합니다.
tsgolint (고)
typescript-go를 사용해 타입스크립트 프로그램을 빌드하고, 타입 인식 규칙을 실행하여 구조화된 진단 정보를 옥린트로 반환합니다.
설치
타입 인식 린트는 추가 종속성 필요합니다:
npm add -D oxlint-tsgolint@latestpnpm add -D oxlint-tsgolint@latestyarn add -D oxlint-tsgolint@latestbun add -D oxlint-tsgolint@latest타입 인식 린트 실행
타입 인식 린트를 포함한 옥린트를 실행하려면 --type-aware 플래그를 전달해야 합니다:
oxlint --type-aware활성화되면 옥린트는 표준 규칙과 typescript/* 네임스페이스의 타입 인식 규칙을 모두 실행합니다.
타입 인식 린트는 선택 사항이며, 플래그가 제공되지 않으면 실행되지 않습니다.
편집기 및 LSP 기반 통합(예: VS Code)에서 타입 인식 린트는 typeAware 옵션을 true로 설정함으로써 활성화할 수 있습니다. 자세한 내용은 편집기 페이지를 참조하세요.
모노레포 및 빌드 출력물
타입 인식 린트는 해석된 타입 정보가 필요합니다.
모노레포의 경우:
.d.ts파일이 사용 가능하도록 종속 패키지를 빌드합니다.- 실행하기 전에 종속성을 설치합니다.
pnpm install
pnpm -r build
oxlint --type-aware타입 체크 진단
타입 체크를 활성화하면 린트 결과와 함께 타입스크립트 오류도 보고됩니다:
oxlint --type-aware --type-check이 모드는 CI에서 별도의 tsc --noEmit 단계를 대체할 수 있습니다:
# 이전
tsc --noEmit
oxlint
# 이후
oxlint --type-aware --type-check타입 인식 규칙 구성
타입 인식 규칙은 다른 옥린트 규칙과 동일한 방식으로 구성됩니다.
{
"plugins": ["typescript"],
"rules": {
"typescript/no-floating-promises": "error",
"typescript/no-unsafe-assignment": "warn"
}
}규칙은 그들의 typescript-eslint 등가 항목과 동일한 옵션을 지원합니다.
{
"plugins": ["typescript"],
"rules": {
"typescript/no-floating-promises": ["error", { "ignoreVoid": true }]
}
}비활성화 주석
타입 인식 규칙은 인라인 비활성화 주석을 지원합니다:
// oxlint-disable-next-line typescript/no-floating-promises
doSomethingAsync();사용되지 않는 비활성화 주석을 보고하려면 다음을 사용하세요:
oxlint --type-aware --report-unused-disable-directives타입스크립트 호환성
타입 인식 린트는 typescript-go에 의해 구동됩니다.
- 타입스크립트 7.0 이상이 필요합니다
- 일부 구식
tsconfig옵션이 지원되지 않습니다(예:tsconfig.json내의baseUrl) - 타입스크립트 6.0에서 폐기되거나 7.0에서 제거된 구성 옵션/기능을 사용 중이라면, 먼저 코드베이스를 마이그레이션해야 합니다
--type-check가 활성화될 때 유효하지 않은 옵션이 경고됩니다
자세한 내용은 타입스크립트 마이그레이션 가이드를 참조하세요. 또한 ts5to6를 사용해 tsconfig 파일을 업그레이드하는 것을 고려하세요.
안정성 참고 사항
타입 인식 린트는 알파 상태입니다:
- 규칙 커버리지가 완전하지 않음
- 매우 큰 코드베이스에서는 높은 메모리 사용량 발생 가능성 있음
- 성능은 계속 향상됨
문제 해결
성능 및 디버깅
타입 인식 린트가 느리거나 과도한 메모리를 사용하는 경우:
- 두 도구 모두 업데이트:
oxlintoxlint-tsgolint
- 디버그 로깅 활성화:
OXC_LOG=debug oxlint --type-aware예시 출력(핵심 시간 지점 표시):
2026/01/01 12:00:00.000000 tsgolint 시작
2026/01/01 12:00:00.001000 파일을 프로그램에 할당하기 시작. 총 파일 수: 259
2026/01/01 12:00:01.000000 파일 할당 완료. 총 프로그램 수: 8. 매칭되지 않은 파일: 75
2026/01/01 12:00:01.001000 12개의 워커로 린터 시작
2026/01/01 12:00:01.001000 작업 배분: 8개 프로그램
2026/01/01 12:00:01.002000 [1/8] 프로그램 린터 실행: /path/to/project/jsconfig.json
...
2026/01/01 12:00:01.100000 [4/8] 프로그램 린터 실행: /path/to/project/tsconfig.json
2026/01/01 12:00:02.500000 26140개의 소스 파일로 프로그램 생성됨
2026/01/01 12:00:14.000000 /path/to/project/oxlint-plugin.mts
...
2026/01/01 12:00:14.100000 [5/8] 프로그램 린터 실행: /path/to/project/apps/tsconfig.json
...
2026/01/01 12:00:15.000000 린팅 완료
259개 파일에 161개 규칙을 사용해 12개 스레드로 16.4초 소요로그 해석 방법:
- 파일 할당 단계 (
파일 할당 시작...→파일 할당 완료...): 소스 파일을tsconfig프로젝트에 매핑합니다. 이 단계는 빠르게 이루어져야 합니다. 느릴 경우 이슈를 등록하세요. - 프로그램 린팅 (
[N/M] 프로그램 린터 실행...): 각 타입스크립트 프로젝트는 별도로 린팅됩니다. 상당히 오래 걸리는 프로그램은 비용이 큰 타입 해결이나 너무 큰 프로젝트를 나타낼 수 있습니다.- 소스 파일 수가 비정상적으로 많은 프로그램을 확인하세요 (예:
프로그램 생성 완료: 26140개의 소스 파일). 이는tsconfig의includes/excludes설정이 불필요한 파일(예:node_modules)까지 포함하고 있음을 시사할 수 있습니다. - 로깅된 각 파일 경로는 해당 파일이 린팅되는 시점을 나타냅니다. 파일 간에 큰 시간 간격이 있다면 특정 파일의 타입 해결이 비용이 클 수 있음을 의미합니다.
- 소스 파일 수가 비정상적으로 많은 프로그램을 확인하세요 (예:
일반적인 성능 문제
루트 tsconfig가 너무 많은 파일 포함
너무 광범위한 include 패턴을 가진 루트 tsconfig.json은 리포지토리 내 모든 파일을 포함할 수 있어 심각한 지연을 초래할 수 있습니다:
{
"include": ["**/*"] // ❌ 모든 것을 포함
}이 구성은 빌드 출력물과 타입 체크할 필요 없는 다른 파일들을 포함합니다.
수정: 명시적으로 include 패턴을 범위 제한하고 적절한 exclude 항목을 추가하세요:
{
"include": ["src/**/*"], // ✅ 소스 파일만 포함
"exclude": ["dist", "build", "coverage"] // node_modules는 기본적으로 제외됨
}모노레포의 경우 루트 tsconfig.json이 직접 소스 파일을 포함하지 않도록 확인하세요:
{
"files": []
}문제 진단: 디버그 로깅을 활성화하고 소스 파일 수가 비정상적으로 많은 프로그램을 찾으세요:
2026/01/01 12:00:02.500000 26140개의 소스 파일로 프로그램 생성됨한 프로그램에 수천 개의 파일이 있는 경우, tsconfig의 include/exclude 설정이 올바른지 확인하세요.