SourceFile

The root Node of one parsed file. SourceFiles are the unit of work for parsing, binding, and emit; the Program is essentially a graph of them.

Definition

SourceFile lives in src/compiler/types.ts and inherits from Declaration. Highlights:

Field	Role
kind: SyntaxKind.SourceFile	Constant
fileName: string	Original filename, as passed to the parser
path: Path	Normalised, branded path used as a map key
text: string	Raw source text
languageVersion: ScriptTarget	What --target was in effect
languageVariant: LanguageVariant	Standard or JSX
scriptKind: ScriptKind	TS, TSX, JS, JSX, JSON, External, Deferred
statements: NodeArray<Statement>	Top-level statements
endOfFileToken: EndOfFileToken	Anchors trailing trivia
isDeclarationFile: boolean	True for .d.ts
externalModuleIndicator?: Node	Set by the binder when import/export is present
commonJsModuleIndicator?: Node	Set by the binder when module.exports/exports.x is present
parseDiagnostics: DiagnosticWithLocation[]	Errors caught at parse time
bindDiagnostics: DiagnosticWithLocation[]	Errors caught at bind time
commentDirectives?: CommentDirective[]	// @ts-ignore / // @ts-expect-error / // @ts-nocheck
pragmas: ReadonlyMap<string, PragmaPseudoMap[keyof PragmaPseudoMap]>	Triple-slash directives, JSX pragmas
referencedFiles: FileReference[]	/// <reference path="…" />
typeReferenceDirectives: FileReference[]	/// <reference types="…" />
libReferenceDirectives: FileReference[]	/// <reference lib="…" />
imports: StringLiteralLike[]	All import specifiers (and require() / dynamic import() arguments in JS-aware mode)
moduleAugmentations: StringLiteral[]	declare module "x" blocks
ambientModuleNames: string[]	declare module "x" { … } global declarations
redirectInfo?	When the program substitutes a .d.ts for a .ts (project references)
lineMap?	Lazy newline-position cache used by getLineAndCharacterOfPosition
nodeCount, identifierCount, identifiers	Stats and the file's identifier interning table

Construction

createSourceFile(fileName, sourceText, options) (in src/compiler/parser.ts) is the public entry. The options argument is either a ScriptTarget or a CreateSourceFileOptions:

interface CreateSourceFileOptions {
  languageVersion: ScriptTarget;
  impliedNodeFormat?: ResolutionMode;
  setExternalModuleIndicator?: (file: SourceFile) => void;
  jsDocParsingMode?: JSDocParsingMode;
}

impliedNodeFormat is the per-file CJS/ESM determination from node16/nodenext, computed by the program before the parser is invoked.

Updating

updateSourceFile(sourceFile, newText, textChangeRange, aggressiveChecks?) does an incremental re-parse. The compiler reuses unchanged subtrees by walking the original tree and re-parsing only intersecting regions. See systems/parser for the algorithm.

Per-file caches

Most lazy state is hung off the SourceFile:

• lineMap — newline positions.
• nameTable — used by find-references for fast string→positions lookup.
• resolvedModules, resolvedTypeReferenceDirectiveNames — imported-module resolution results.
• bindDiagnostics — set after the file is bound.

Putting these on the SourceFile is what makes incremental rebuilds cheap: when a file is reused unchanged, all its caches survive.

Helper functions

• isExternalModule(file) — checks externalModuleIndicator.
• isJSFile(file), isJsonFile(file), isDeclarationFile(file) — sugar.
• getLineAndCharacterOfPosition(file, position) — uses the lazy lineMap.
• getPositionOfLineAndCharacter(file, line, char) — inverse.
• getLeadingCommentRangesOfNode(node, sourceFile), getTrailingCommentRanges — trivia walks.

Integration points

• Created by createSourceFile (parser).
• Bound by bindSourceFile lazily.
• Held by Program and tsserver ScriptInfo.
• Re-emitted into .js / .d.ts / .map by the emitter for non-declaration files.

See primitives/node, systems/parser, and systems/binder.