TypeScript 컴파일러 내부 구조

컴파일러가 하는 일

TypeScript 컴파일러는 코드를 읽어서(구문), 뜻을 따지고(의미), JavaScript로 내보낸다. 대부분의 트랜스파일러(Babel, esbuild)는 구문만 다룬다. TypeScript를 「타입 검사기」로 만드는 것은 그 사이의 의미 분석, 즉 바인더와 체커다.

문법(syntax)과 의미(semantics)는 다르다. const foo: number = 'not a number'는 문법적으로 완벽하다. 파서는 문제없이 트리를 만든다. 틀린 것은 뜻이고, 그것은 체커가 잡는다.

flowchart TB
  src["소스 코드"] -->|"scanner"| tok["토큰 열"]
  tok -->|"parser"| ast["AST (SourceFile)"]
  ast -->|"binder<br/>AST 노드 ↔ Symbol 연결"| chk["checker: AST + Symbol로 타입 검사"]
  chk --> diag["진단(오류 목록)"]
  chk --> emit["emitter: AST + checker의 판단"]
  emit --> out[".js · .d.ts · .map"]

주요 자료 구조

스캐너와 파서

스캐너는 파서가 부를 때마다 다음 토큰 하나를 돌려준다. 매번 새로 만들지 않고 하나를 재사용하며, 파서가 파일을 시작할 때 텍스트와 옵션으로 상태를 다시 맞춘다. var foo = 123;은 이렇게 잘린다.

VarKeyword  Identifier  EqualsToken  NumericLiteral  SemicolonToken
  0-3          3-7         7-9           9-13            13-14

foo의 범위가 3-7인 것은 앞 공백까지 포함하기 때문이다(아래 「트리비아」). 파서는 이 토큰으로 트리를 만든다.

SourceFile 0-14
└─ VariableStatement 0-14
   ├─ VariableDeclarationList 0-13
   │  └─ VariableDeclaration 3-13
   │     ├─ Identifier "foo" 3-7
   │     └─ NumericLiteral "123" 9-13
   └─ SemicolonToken 13-14
EndOfFileToken 14-14

AST를 직접 보려면 TypeScript AST Viewer 같은 도구가 편하다. 코드로는 typescript 패키지의 API로 순회한다.

import ts from 'typescript';
 
const sf = ts.createSourceFile('a.ts', 'var foo = 123;', ts.ScriptTarget.Latest, true);
 
function walk(node: ts.Node, depth = 0): void {
  console.log(' '.repeat(depth * 2) + ts.SyntaxKind[node.kind], node.pos, node.end);
  ts.forEachChild(node, (child) => walk(child, depth + 1));
}
walk(sf);

forEachChild는 의미 있는 자식만 돌고 키워드·구두점 토큰은 건너뛴다. 토큰까지 모두 보려면 node.getChildren()을 쓴다. SyntaxKind에는 범위 표시용 별칭(FirstStatement, FirstLiteralToken, FirstAssignment)이 같은 숫자로 들어 있어서, ts.SyntaxKind[node.kind]는 VariableStatement 대신 FirstStatement처럼 별칭 이름을 돌려주기도 한다.

트리비아: 주석과 공백

공백, 줄바꿈, 주석처럼 실행에는 상관없는 텍스트를 트리비아(trivia) 라 한다. AST에 노드로 저장하지 않아 트리를 가볍게 유지하고, 필요할 때 원문에서 다시 읽는다. 그래서 노드에는 시작점이 두 개다.

• 같은 줄에서 토큰 뒤에 오는 트리비아는 그 토큰의 것이고, 다음 줄부터의 주석은 뒤 토큰의 것이다.
• 파일 맨 앞 트리비아는 첫 토큰이, 맨 끝 트리비아는 길이 0인 파일 끝 토큰이 갖는다.
• ts.getLeadingCommentRanges, ts.getTrailingCommentRanges로 노드 앞뒤 주석을 꺼낸다. JSDoc 기반 도구, 주석을 보존하는 codemod가 이것을 쓴다.

바인더: 심볼과 스코프

심볼(Symbol)은 AST의 선언 노드들을 「같은 것」으로 잇는 의미 단위다. interface User를 두 번 선언하면 노드는 둘이지만 심볼은 하나이고, 체커는 그 심볼의 선언 목록을 합쳐 본다. 선언 병합이 이렇게 일어난다. 반대로 같은 공간에 let x가 두 번이면 바인더가 「Cannot redeclare block-scoped variable」을 낸다.

바인더는 파일 단위로 돌고, 체커가 초기화될 때 모든 파일을 바인딩한 뒤 전역 스크립트 파일의 locals를 전역 심볼 테이블 하나로 합친다. import·export가 없는 파일의 선언이 다른 파일에서 보이는 이유가 이것이다(파일 모듈과 전역 스크립트).

체커: 지연 검사와 진단

체커는 컴파일러에서 가장 큰 부분이다. 프로그램이 처음 만들어질 때 모든 타입을 계산하지 않고, 누군가 물을 때 필요한 만큼만 계산하고 캐시한다. 편집기에서 마우스를 올려 타입을 볼 때, tsc가 진단을 모을 때가 그 「물음」이다. 그래서 언어 서비스는 파일 하나만 바뀌어도 그 주변만 다시 계산한다.

진단은 어디서 나왔는지에 따라 나뉜다.

오류 메시지를 읽는 법과 자주 보는 코드는 TypeScript 오류 메시지 읽기와 흔한 오류에 있다.

이미터: JavaScript, 선언 파일, 소스맵

이미터는 출력할 파일마다 AST를 변환기(transformer) 사슬에 통과시킨다. 타입 표기를 지우고, target보다 새 문법(데코레이터, 클래스 필드 등)을 낮추고, 모듈 형식을 맞춘 뒤 텍스트로 쓴다. 체커는 「이 import는 값으로 쓰였나」 같은 판단을 이미터에 넘겨준다(emit resolver). 그래서 타입 정보 없이 파일 하나씩만 변환하는 Babel·esbuild는 이 판단에 기대는 코드를 처리하지 못하고, isolatedModules·verbatimModuleSyntax가 그런 코드를 미리 막는다.

소스맵(source map) 은 출력 파일의 위치를 원본 위치로 되돌리는 지도다. JSON 안의 mappings 문자열에 「출력의 몇 번째 줄 몇 번째 열 ↔ 원본 파일의 몇 번째 줄 몇 번째 열」을 이전 값과의 차이로, Base64 VLQ로 압축해 담는다. 디버거와 에러 리포터(Sentry 등)가 이것으로 스택 트레이스를 원본 코드로 보여 준다.

TypeScript 7: Go로 옮긴 컴파일러

TypeScript 7.0(2026)은 컴파일러를 TypeScript에서 Go로 옮겨 쓴(port) 버전이다. 새로 설계한 것이 아니라 같은 단계와 같은 검사 규칙을 그대로 옮겼기 때문에, 6.0과 같은 구문 오류와 같은 타입을 낸다.

위의 ts.createSourceFile 예시처럼 JavaScript로 된 컴파일러 API를 쓰는 스크립트는 typescript@6에서 돌린다.

정리

• 스캐너·파서는 구문을, 바인더·체커는 의미를 다룬다. 트랜스파일러에 없는 것이 바인더와 체커다.
• AST는 SyntaxKind로 종류를, pos·end로 위치를 나타내고, 주석·공백은 트리비아로 따로 다룬다.
• 심볼은 여러 선언을 하나로 묶는다. 선언 병합, 중복 선언 오류, 전역 스크립트의 이름 공유가 모두 여기서 나온다.
• 체커는 물을 때만 계산한다. 그래서 편집기가 빠르다.
• 이미터는 변환기로 타입을 지우고 문법을 낮추며, .d.ts와 소스맵을 함께 낸다. TypeScript 7은 같은 구조를 Go로 옮겨 빨라졌다.

타입 검사는 「구문 트리 위에 심볼을 얹고, 필요한 순간에 타입을 계산하는」 일이다.

관련 노트: TypeScript: 개념과 문법 한눈에 보기, TypeScript 프로젝트 설정, TypeScript 오류 메시지 읽기와 흔한 오류, Babel과 AST 변환, JavaScript는 인터프리터 언어일까, 컴파일 언어일까