Program and Compilation

Relevant source files

• src/compiler/binder.ts
• src/compiler/checker.ts
• src/compiler/commandLineParser.ts
• src/compiler/core.ts
• src/compiler/diagnosticMessages.json
• src/compiler/emitter.ts
• src/compiler/moduleNameResolver.ts
• src/compiler/moduleSpecifiers.ts
• src/compiler/parser.ts
• src/compiler/program.ts
• src/compiler/resolutionCache.ts
• src/compiler/scanner.ts
• src/compiler/sys.ts
• src/compiler/tsconfig.json
• src/compiler/types.ts
• src/compiler/utilities.ts
• src/harness/client.ts
• src/harness/fourslashImpl.ts
• src/harness/fourslashInterfaceImpl.ts
• src/harness/harnessLanguageService.ts
• src/harness/tsconfig.json
• src/server/editorServices.ts
• src/server/project.ts
• src/server/protocol.ts
• src/server/scriptInfo.ts
• src/server/scriptVersionCache.ts
• src/server/session.ts
• src/server/tsconfig.json
• src/server/utilities.ts
• src/services/codefixes/importFixes.ts
• src/services/completions.ts
• src/services/exportInfoMap.ts
• src/services/findAllReferences.ts
• src/services/goToDefinition.ts
• src/services/importTracker.ts
• src/services/services.ts
• src/services/tsconfig.json
• src/services/types.ts
• src/services/utilities.ts
• src/testRunner/unittests/tsserver/exportMapCache.ts
• tests/baselines/reference/api/typescript.d.ts
• tests/baselines/reference/tsserver/exportMapCache/invalidates-the-cache-when-a-file-is-opened-with-different-contents.js
• tests/cases/fourslash/fourslash.ts
• tests/cases/fourslash/server/completionsOverridingMethodCrash2.ts

Purpose and Scope

The Program is the central orchestrator of the TypeScript compilation process. It manages source files, coordinates the compilation phases (scanning, parsing, binding, type checking, and emitting), and provides the primary API for compiling TypeScript code into JavaScript.

This document focuses on the Program interface and how it orchestrates the entire compilation pipeline. For details on individual compilation phases, see:

• Scanner for lexical analysis
• Parser for syntax analysis
• Binder for symbol creation and scope management
• Type Checker for semantic analysis
• Emitter for code generation
• Transformation Pipeline for AST transformations

Program Interface Overview

The Program interface is defined in src/compiler/types.ts3252-3341 and serves as the main entry point for TypeScript compilation. It provides methods to access source files, diagnostics, and trigger compilation.

Program Orchestration Diagram

Sources: src/compiler/types.ts3252-3341 src/compiler/program.ts1-150

Key Program Methods

Method Category	Methods	Purpose
Source File Access	getSourceFiles(), getSourceFile(), getRootFileNames()	Access compiled source files
Compilation	emit(), getTypeChecker()	Trigger compilation and code generation
Diagnostics	getSemanticDiagnostics(), getSyntacticDiagnostics(), getDeclarationDiagnostics(), getGlobalDiagnostics()	Retrieve errors and warnings
Configuration	getCompilerOptions(), getCurrentDirectory(), getCommonSourceDirectory()	Access compilation settings
Project Structure	getProjectReferences(), getResolvedProjectReferences()	Multi-project compilation support

Sources: src/compiler/types.ts3252-3341

Creating a Program

Programs are created using the createProgram() factory function src/compiler/program.ts474-500 which orchestrates the initial setup and file discovery.

Program Factory Flow

Sources: src/compiler/program.ts474-500 src/compiler/types.ts3369-3379

CreateProgramOptions Interface

The CreateProgramOptions interface src/compiler/types.ts3369-3379 provides fine-grained control over program creation, including support for oldProgram to enable structure reuse.

CompilerHost Requirements

The CompilerHost interface src/compiler/types.ts3344-3367 abstracts file system operations. Key methods include getSourceFile, writeFile, and resolveModuleNames.

Program Creation Process

The internal createProgram implementation in src/compiler/program.ts502-1530 follows a strict sequence to build the compilation context.

Execution Workflow

Sources: src/compiler/program.ts502-1530

Structure Reuse Optimization

The StructureIsReused enum src/compiler/types.ts3625-3629 determines whether an old program can be reused. The reuse logic in createProgram checks for compiler option compatibility and file changes src/compiler/program.ts1533-1729

Source File Management

The Program maintains a comprehensive map of all source files involved in compilation, including root files, library files, and discovered dependencies.

File Discovery Process

The discovery process in src/compiler/program.ts757-945 follows these steps:

1. Process Root Files: Load each file from rootNames.
2. Process Triple-Slash References: Scan for path and type references.
3. Resolve Module Imports: Follow import and export statements.
4. Add Library Files: Include lib.d.ts based on the target.

Each discovered file is loaded via CompilerHost.getSourceFile() src/compiler/program.ts983-1049 which triggers the Parser.

Compilation Phase Orchestration

The Program coordinates compilation phases lazily, creating components like the TypeChecker only when requested.

Phase Coordination Workflow

Sources: src/compiler/program.ts1500-1530 src/compiler/program.ts2156-2279

Lazy Binding and Type Checking

Binding is triggered on first semantic access src/compiler/program.ts2156-2217 The TypeChecker is created via createTypeChecker(program) src/compiler/program.ts2232-2279 which is defined in src/compiler/checker.ts1-117

Diagnostics Collection

The Program provides multiple diagnostic collection methods, each serving a different purpose, such as getSyntacticDiagnostics for parse errors and getSemanticDiagnostics for type errors src/compiler/program.ts2638-2953

Diagnostic Categories

Category	Source	Method
Syntactic	Parser	getSyntacticDiagnostics()
Global	Program	getGlobalDiagnostics()
Semantic	Type Checker	getSemanticDiagnostics()
Declaration	Emitter	getDeclarationDiagnostics()

Sources: src/compiler/program.ts2638-2953

Emit Process

The emit() method src/compiler/program.ts3065-3229 orchestrates code generation by creating an EmitResolver and invoking emitFiles src/compiler/emitter.ts1-75

Emit Flow

Sources: src/compiler/program.ts3065-3229 src/compiler/emitter.ts1-100

Incremental Compilation and Project References

TypeScript supports incremental compilation through the BuilderProgram interface src/compiler/types.ts3631-3709 This allows for faster rebuilds by tracking affected files and reusing cached diagnostics.

Project References

Project references enable multi-project compilation with proper dependency ordering src/compiler/program.ts1100-1300 The Program resolves these via ResolvedProjectReference src/compiler/types.ts3602-3608

Sources: src/compiler/types.ts3631-3709 src/compiler/program.ts1100-1300