디버깅

OXC_LOG 환경 변수

OXC_LOG 환경 변수는 oxlint와 oxfmt에서 런타임 트레이싱을 켭니다. 설정하지 않으면 로깅은 완전히 꺼져 비용이 없습니다.

기본 사용법

# oxlint 디버그 로그
OXC_LOG=debug oxlint

# oxfmt 디버그 로그
OXC_LOG=debug oxfmt

# import 플러그인 사용 시 resolver 트레이싱
OXC_LOG=oxc_resolver oxlint --import-plugin

# 포매터 트레이싱
OXC_LOG=oxc_formatter oxfmt

필터 문법

OXC_LOG는 tracing-subscriber 필터 문법을 사용합니다.

패턴	설명
debug	모든 모듈에 debug 수준 로그
trace	모든 모듈에 trace 수준 로그
oxc_resolver	oxc_resolver 모듈의 모든 로그
oxc_resolver=debug	oxc_resolver에 debug 수준만
oxc_resolver=trace	oxc_resolver에 trace 수준만
oxc_formatter,oxc_resolver	여러 모듈 동시에 켜기

출력

로그는 린터 진단이나 포맷 결과 stdout과 섞이지 않도록 stderr에 씁니다. oxfmt에서는 멀티스레드 동작 디버깅을 위해 스레드 이름과 스팬 타이밍 정보를 포함합니다.

자주 쓰는 경우

처리 중인 파일 목록 보기:

OXC_LOG=debug oxlint
OXC_LOG=debug oxfmt

모듈 해석 문제 디버깅:

OXC_LOG=oxc_resolver=debug oxlint --import-plugin

rust-lldb

디버그 빌드에서 패닉 정보를 보려면 rust-lldb를 쓸 수 있습니다.

디버그 심볼 켜기:

[profile.release]
debug = true
strip = false
panic = "unwind"

바이너리 빌드:

cargo build --release --bin oxlint --features allocator

실행:

rust-lldb -- ./target/release/oxlint

실행 후 r로 프로그램을 실행합니다.

VSCode에서 TypeScript 디버깅

TypeScript 저장소 디버깅 가이드에 따르면:

• .vscode/launch.template.json을 launch.json으로 이름 변경
• tests/cases/compiler/foo.ts 추가
• "${fileBasenameNoExtension}"를 foo.ts로 변경
• TypeScript 소스 어딘가에 브레이크포인트 설정
• 메뉴 "실행 - 디버깅" 또는 F5
• 디버깅 중 tsc는 대상 테스트 파일 전에 전역 .d.ts를 평가
• src/compiler/debug.ts의 Debug.formatXXX(value)로 enum 값 출력 가능
• "WATCH"로 관심 있는 값 확인

VSCode에서 Linter 디버깅

CodeLLDB로 다른 곳의 npm 프로젝트에 대해 Linter를 디버그하기 쉽습니다.

.vscode/launch.json에서 필요에 맞게 다음 필드를 바꿉니다.

• cwd: npm 프로젝트의 절대 경로
• args: 린터에 넘길 인자

{
  "type": "lldb",
  "request": "launch",
  "name": "Debug Oxlint",
  "cargo": {
    "env": {
      "RUSTFLAGS": "-g"
    },
    "args": ["build", "--bin=oxlint", "--package=oxlint"],
    "filter": {
      "name": "oxlint",
      "kind": "bin"
    }
  },
  "cwd": "PATH-TO-TEST-PROJECT", 
  "args": ["--ARGS-TO-OXLINT"] 
}

VS Code 디버깅 패널에서 Debug Oxlint를 고른 뒤 디버깅을 시작합니다.

지정한 cwd에서 디버그 프로세스가 시작되어, 테스트 프로젝트에서 린터를 돌리며 디버거를 붙인 것과 같습니다.