Oxc

타입 인식 린팅 ​

타입 인식 린팅은 TypeScript 타입 시스템에 의존하는 규칙을 켭니다. 예를 들어 처리되지 않은 Promise나 안전하지 않은 대입을 찾습니다. Oxlint에서는 tsgolint가 타입 인식 린팅을 제공하며 Oxlint CLI·설정과 통합되어 있습니다.

타입 인식 린팅은 현재 typescript-eslint의 타입 인식 규칙 61개 중 59개를 지원합니다. 규칙 커버리지·성능·호환성은 계속 개선 중입니다.

개요 ​

Oxlint는 두 구성 요소로 역할을 나눕니다:

  • Oxlint(Rust)
    파일 순회, 무시 로직, 설정, 타입 비인식 규칙, 리포팅을 담당합니다.

  • tsgolint(Go)
    typescript-go로 TypeScript 프로그램을 만들고 타입 인식 규칙을 실행한 뒤, 구조화된 진단을 Oxlint로 돌려줍니다.

설치 ​

타입 인식 린팅에는 추가 의존성이 필요합니다:

sh
npm add -D oxlint-tsgolint@latest
sh
pnpm add -D oxlint-tsgolint@latest
sh
yarn add -D oxlint-tsgolint@latest
sh
bun add -D oxlint-tsgolint@latest

타입 인식 린팅 실행 ​

다음 둘 중 한 곳에서 켤 수 있습니다:

  • CLI 플래그: --type-aware
  • 루트 설정: options.typeAware: true

CLI:

bash
oxlint --type-aware

루트 설정:

json
{
  "options": {
    "typeAware": true
  }
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  options: {
    typeAware: true,
  },
});

켜면 일반 규칙과 typescript/* 네임스페이스의 타입 인식 규칙이 함께 실행됩니다.

--type-aware는 설정 파일보다 우선합니다. 예: oxlint --type-aware -c .oxlintrc.json은 해당 설정에 options.typeAware: false가 있어도 타입 인식 린팅을 켭니다.

options.typeAware와 options.typeCheck는 루트 설정 파일에서만 지원됩니다. 중첩 설정에서는 이 필드를 쓰면 안 됩니다.

VS Code 같은 에디터·LSP 통합에서는 typeAware 옵션을 true로 설정하면 됩니다. 자세한 내용은 에디터 페이지를 참고하세요.

모노레포와 빌드 산출물 ​

타입 인식 린팅은 해석된 타입 정보가 필요합니다.

모노레포에서는:

  • 의존 패키지를 빌드해 .d.ts가 준비되게 하세요
  • 실행 전에 의존성 설치가 끝났는지 확인하세요
bash
pnpm install
pnpm -r build
oxlint --type-aware

타입 검사 진단 ​

타입 검사를 켜면 린트 결과와 함께 TypeScript 오류도 표시됩니다:

bash
oxlint --type-aware --type-check

또는 루트 설정에서:

json
{
  "options": {
    "typeAware": true,
    "typeCheck": true
  }
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  options: {
    typeAware: true,
    typeCheck: true,
  },
});

--type-check도 설정 파일보다 우선합니다. 예: oxlint --type-check -c .oxlintrc.json은 설정에 options.typeCheck: false가 있어도 타입 검사를 켭니다.

이 모드는 CI에서 별도의 tsc --noEmit 단계를 대체할 수 있습니다:

bash
# 이전
tsc --noEmit
oxlint

# 이후
oxlint --type-aware --type-check

타입 인식 규칙 설정 ​

타입 인식 규칙은 다른 Oxlint 규칙과 동일하게 설정합니다.

json
{
  "plugins": ["typescript"],
  "rules": {
    "typescript/no-floating-promises": "error",
    "typescript/no-unsafe-assignment": "warn"
  }
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: ["typescript"],
  rules: {
    "typescript/no-floating-promises": "error",
    "typescript/no-unsafe-assignment": "warn",
  },
});

규칙 옵션은 해당 typescript-eslint 규칙과 동일하게 지원합니다.

json
{
  "plugins": ["typescript"],
  "rules": {
    "typescript/no-floating-promises": ["error", { "ignoreVoid": true }]
  }
}
ts
import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: ["typescript"],
  rules: {
    "typescript/no-floating-promises": ["error", { ignoreVoid: true }],
  },
});

비활성화 주석 ​

타입 인식 규칙은 인라인 비활성화 주석을 지원합니다:

ts
// oxlint-disable-next-line typescript/no-floating-promises
doSomethingAsync();

사용되지 않는 비활성화 주석을 보고하려면:

bash
oxlint --type-aware --report-unused-disable-directives

TypeScript 호환성 ​

타입 인식 린팅은 typescript-go를 사용합니다.

  • TypeScript 7.0+ 필요
  • 일부 레거시 tsconfig 옵션은 미지원(tsconfig.json의 baseUrl 등)
  • TypeScript 6.0에서 폐기되었거나 7.0에서 제거된 설정·기능을 쓰는 경우 먼저 코드베이스를 옮겨야 할 수 있음
  • 잘못된 옵션은 --type-check가 켜져 있을 때 보고됨

자세한 내용은 TypeScript 마이그레이션 가이드를 참고하고, tsconfig 업그레이드에는 ts5to6 사용을 고려하세요.

안정성 참고 ​

타입 인식 린팅은:

  • 규칙 커버리지가 아직 완전하지 않음(하지만 거의 근접)
  • 아주 큰 코드베이스에서는 메모리 사용량이 높을 수 있음
  • 성능은 계속 개선 중

문제 해결 ​

성능과 디버깅 ​

타입 인식 린팅이 느리거나 메모리를 과다 사용하면:

  1. 두 도구 모두 최신으로 유지:
  • oxlint
  • oxlint-tsgolint
  1. 디버그 로깅 켜기:
bash
OXC_LOG=debug oxlint --type-aware

예시 출력(주요 타이밍):

2026/01/01 12:00:00.000000 Starting tsgolint
2026/01/01 12:00:00.001000 Starting to assign files to programs. Total files: 259
2026/01/01 12:00:01.000000 Done assigning files to programs. Total programs: 8. Unmatched files: 75
2026/01/01 12:00:01.001000 Starting linter with 12 workers
2026/01/01 12:00:01.001000 Workload distribution: 8 programs
2026/01/01 12:00:01.002000 [1/8] Running linter on program: /path/to/project/jsconfig.json
...
2026/01/01 12:00:01.100000 [4/8] Running linter on program: /path/to/project/tsconfig.json
2026/01/01 12:00:02.500000 Program created with 26140 source files
2026/01/01 12:00:14.000000 /path/to/project/oxlint-plugin.mts
...
2026/01/01 12:00:14.100000 [5/8] Running linter on program: /path/to/project/apps/tsconfig.json
...
2026/01/01 12:00:15.000000 Linting Complete
Finished in 16.4s on 259 files with 161 rules using 12 threads.

로그 읽는 법:

  • 파일 할당 단계 (Starting to assign files... → Done assigning files...): 소스 파일을 tsconfig 프로젝트에 매핑합니다. 보통 빠릅니다. 느리면 이슈를 등록해 주세요.
  • 프로그램 린팅 ([N/M] Running linter on program...): TypeScript 프로젝트마다 따로 린트합니다. 특정 프로그램만 유난히 길면 타입 해석 비용이 크거나 프로젝트가 과도하게 클 수 있습니다.
    • 소스 파일 수가 비정상적으로 많은 프로그램(예: Program created with 26140 source files)을 찾아보세요. include/exclude가 잘못되어 node_modules 등 불필요한 파일이 들어온 경우일 수 있습니다.
    • 로그에 찍히는 파일 경로는 해당 파일을 린트하는 시점입니다. 파일 사이 간격이 크면 특정 파일에서 타입 해석이 비싼 것일 수 있습니다.

흔한 성능 이슈 ​

루트 tsconfig가 너무 많은 파일을 포함 ​

루트 tsconfig.json의 include가 넓으면 저장소 전체가 들어와 크게 느려질 수 있습니다:

tsconfig.json
json
{
  "include": ["**/*"] // ❌ 모든 것을 포함
}

이 설정은 빌드 산출물 등 타입 검사 대상이 아닌 파일까지 끌어옵니다.

해결: include 범위를 명확히 하고 적절한 exclude를 둡니다:

tsconfig.json
json
{
  "include": ["src/**/*"], // ✅ 소스만
  "exclude": ["dist", "build", "coverage"] // node_modules는 기본 제외
}

모노레포에서는 루트 tsconfig.json이 소스 파일을 직접 포함하지 않도록 하세요:

tsconfig.json
json
{
  "files": []
}

진단: 디버그 로깅을 켜고 프로그램당 소스 파일 수가 비정상적으로 많은지 확인합니다:

2026/01/01 12:00:02.500000 Program created with 26140 source files

한 프로그램에 수천 개 파일이 보이면 해당 tsconfig의 include/exclude를 점검하세요.

다음 단계 ​

© 2026 VoidZero Inc. and Oxc contributors.