# microsoft/TypeScript — codebase unpack

> Canonical page: https://codevetter.com/unpack/typescript

This is a deterministic Repo Unpack scan of microsoft/TypeScript — a structural map, not a review, security audit, or maintainer-endorsed description.

- Scanned commit: 5f6db9c9148635b4cbf72f1193b821b9c6b42dcc (2026-09-22)
- Last upstream commit: Remove implicit floating-point FMAs (#64323)
- Generated by codevetter 1.12.0 on 2026-09-22
- 3997 files scanned · 9.0 MB

## Languages

- TypeScript: 13158 files
- JavaScript: 13133 files
- Go: 5119 files
- JSON: 185 files
- Markdown: 66 files
- YAML: 34 files

## Repository structure

- tsc/ — 3697 files
- packages/ — 185 files
- tools/ — 67 files
- .github/ — 31 files
- .devcontainer/ — 1 files

Probable source entrypoint: `packages/` (inferred from the tree, not upstream docs)

## Source layout — packages/

- packages/typescript/ — 148 files
- packages/vscode-typescript/ — 33 files
- packages/vscode-typescript-nightly/ — 4 files

## Package

- package.json: @typescript/repo v0.0.0 — 13 declared dependencies

## Structural health signals

Average score 7.1/10 across 96 files; 28 hotspots. These are deterministic review leads, not proof of a bug.

## Recent history

- 5f6db9c91486 (2026-09-22) Remove implicit floating-point FMAs (#64323)
- 5b20f2000e76 (2026-09-22) Check JSDoc function type predicates (#64303)
- 1ac2d5aed0bf (2026-09-21) Make all the codegen we do incremental (#64331)
- 36482c8dbb89 (2026-09-21) Fix import statement completion filtering in tsgo (#64357)
- 145b158cf1e7 (2026-09-21) Remove misplaced parameter description from RegExp#source JSDoc (#64352)

## Overview

This repo is the native Go port of the TypeScript compiler and language service (TypeScript 7, internally 'Corsa', shipped as tsgo). A single Go module under tsc/ builds one `tsc` binary that runs in three modes: batch compiler (tsc/tsc -b/--watch), an LSP server (`tsc --lsp`), and an IPC API server (`tsc --api`, MessagePack or JSON-RPC) consumed by the `@typescript/typescript` npm package. The repo also ships the `native-preview` ('TypeScript 7') VS Code extension that spawns the Go binary as a language server, plus extensive baseline-test infrastructure ported from the original TypeScript test suite.

## System map

The system is one Go module (tsc/, module github.com/microsoft/TypeScript/tsc) in a go.work workspace with a tools/ module, orchestrated by a Node hereby build (Herebyfile.mjs). The single binary at tsc/cmd/tsc multiplexes three runtimes: batch compile via internal/execute, an LSP server via internal/lsp over stdin/stdout, and a programmatic API server via internal/api over stdio or a named pipe. The compiler core is layered scanner/parser/ast -> binder -> checker (parallel checker pool) -> transformers -> emitter/printer/sourcemap, all reading through a vfs.FS abstraction with lib .d.ts files embedded via internal/bundled. Shipping surfaces are the `tsc`/`tsgo` binary, per-platform npm packages wrapped by packages/typescript, and the packages/vscode-typescript VS Code extension.
- The only product entrypoint is tsc/cmd/tsc/main.go: runMain() applies a debug stack limit, routes `tsc --lsp` to runLSP and `tsc --api` to runAPI, and otherwise calls execute.CommandLine with the real OS system. — [tsc/cmd/tsc/main.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/cmd/tsc/main.go)
- The compiler core lives in tsc/internal packages layered as scanner -> parser -> ast -> binder -> checker, with module resolution in internal/module and emit in internal/transformers, internal/printer and internal/sourcemap. — [tsc/internal/parser/parser.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/parser/parser.go) [tsc/internal/binder/binder.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/binder/binder.go) [tsc/internal/checker/checker.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/checker/checker.go) [tsc/internal/compiler/program.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/compiler/program.go)
- compiler.NewProgram drives program construction: it calls processAllProgramFiles (the file loader/parse-task machinery in filesparser.go/fileloader.go), then initCheckerPool and verifyCompilerOptions. — [tsc/internal/compiler/program.go#L284-L294](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/compiler/program.go#L284-L294) [tsc/internal/compiler/filesparser.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/compiler/filesparser.go)
- All file IO goes through the vfs.FS interface (FileExists, ReadFile, WriteFile, GetAccessibleEntries, Realpath, ...); the CLI wraps the real OS FS with bundled.WrapFS so embedded lib.d.ts files are served from the binary. — [tsc/internal/vfs/vfs.go#L8-L43](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/vfs/vfs.go#L8-L43) [tsc/internal/bundled/bundled.go#L21-32](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/bundled/bundled.go#L21-L32) [tsc/cmd/tsc/sys.go#L124-138](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/cmd/tsc/sys.go#L124-L138)
- Build/test/lint/format/generate tasks are defined in Herebyfile.mjs; `npx hereby build` runs `go build ./cmd/tsc` into built/local/tsc and copies tsc/internal/bundled/libs into built/local. — [Herebyfile.mjs#L256-288](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/Herebyfile.mjs#L256-L288) [package.json](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/package.json)
- The repo is a Go workspace (go.work) containing modules tsc/ and tools/, requiring Go 1.27; the tsc module pins a small dependency set (go-winio, klauspost/compress, mackerelio/go-osstat, zeebo/xxh3, golang.org/x/*, gotest.tools). — [go.work](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/go.work) [tsc/go.mod](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/go.mod) [tools/go.mod](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tools/go.mod)
- The LSP server is internal/lsp.Server; its request dispatch is a lazily-built handlerMap (handlers()) mapping lsproto.Method values to registered handlers, with lsproto/lsp_generated.go generated from the upstream LSP meta-model. — [tsc/internal/lsp/server.go#L1224-1298](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/server.go#L1224-L1298) [tsc/internal/lsp/lsproto/lsp_generated.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/lsproto/lsp_generated.go) [Herebyfile.mjs#L558-567](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/Herebyfile.mjs#L558-L567)
- The programmatic API server (internal/api.StdioServer) accepts a connection over an ipc.Transport (stdio or named pipe/unix socket) and speaks either MessagePack (sync) or JSON-RPC (async) against a project.Session. — [tsc/internal/api/server.go#L62-120](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/api/server.go#L62-L120) [tsc/internal/ipc/conn.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/ipc/conn.go) [tsc/cmd/tsc/api.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/cmd/tsc/api.go)
- The npm package @typescript/typescript exposes a `tsc` bin that is a Node shim (bin/tsc -> lib/tsc.js) which resolves the platform-specific Go binary via lib/getExePath.js and execve/execFileSync's it. — [packages/typescript/package.json#L35-37](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/typescript/package.json#L35-L37) [packages/typescript/bin/tsc](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/typescript/bin/tsc) [packages/typescript/lib/tsc.js](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/typescript/lib/tsc.js) [packages/typescript/lib/getExePath.js](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/typescript/lib/getExePath.js)
- The VS Code extension 'native-preview' (display name 'TypeScript 7') activates on JS/TS languages and starts the Go server by spawning the resolved exe with args ['--lsp', ...pprofArgs] through vscode-languageclient. — [packages/vscode-typescript/package.json#L31-36](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/vscode-typescript/package.json#L31-L36) [packages/vscode-typescript/src/client.ts#L233-256](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/vscode-typescript/src/client.ts#L233-L256) [packages/vscode-typescript/src/extension.ts](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/vscode-typescript/src/extension.ts)
- internal/fswatch is a vendored, pure-Go (no cgo) filesystem watcher ported from @parcel/watcher, with per-OS backends including fanotify/inotify on Linux, FSEvents via hand-written arm64/amd64 assembly FFI on Darwin, and kqueue. — [tsc/internal/fswatch/README.md](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/fswatch/README.md) [tsc/internal/fswatch/fsevents_darwin_ffi_arm64.s](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/fswatch/fsevents_darwin_ffi_arm64.s) [tsc/internal/fswatch/inotify_linux.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/fswatch/inotify_linux.go)
- Release packaging is driven by hereby tasks (typescript:release, vscode-typescript:release) invoked from CI's release-build job and by Azure pipelines under tools/pipelines (typescript-build.yml, typescript-publish.yml, vscode-typescript-publish.yml). — [.github/workflows/ci.yml#L31-43](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/.github/workflows/ci.yml#L31-L43) [tools/pipelines/typescript-publish.yml](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tools/pipelines/typescript-publish.yml) [Herebyfile.mjs#L102-127](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/Herebyfile.mjs#L102-L127)
- tools/ holds a golangci-lint module plugin (customlint) registering repo-specific analyzers (bitclear, checkchildren, cleanup, emptycase, forbidparentaccess, shadow, unexportedapi), plus utilities like checkmodpaths and gen-proto. — [tools/customlint/plugin.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tools/customlint/plugin.go) [tools/cmd/checkmodpaths](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tools/cmd/checkmodpaths) [tools/gen-proto/main.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tools/gen-proto/main.go)

## Feature catalog

User-facing surface area splits into four groups. (1) The tsc CLI: single-project and build-mode compilation, watch mode, incremental/tsbuildinfo, --init/--showConfig/--listFilesOnly, tracing, pprof, diagnostics statistics. (2) A broad LSP feature set: pull diagnostics, hover, completions with auto-imports, definitions/references/implementations, rename, formatting, code actions, code lenses, inlay hints, semantic tokens, call hierarchy, workspace symbols, folding/selection/linked-editing, willRenameFiles, plus custom debugging and content-mapper methods. (3) A ~300-method programmatic API over IPC (parse, transpile, symbol/type queries, diagnostics, emit). (4) The VS Code extension's commands and settings. Notably, CHANGES.md documents deliberate feature removals versus the Strada compiler (Closure-style JSDoc features, constructor expandos, several removed options).
- `tsc` batch mode resolves a tsconfig.json via -p/--project or an ancestor-directory search (findConfigFile), supports --watch, --init (WriteConfigFile), --version, --help/--all, --showConfig, and rejects incompatible flag combos like --watch with --listFilesOnly. — [tsc/internal/execute/tsc.go#L122-267](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc.go#L122-L267) [tsc/internal/execute/tsc/help.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc/help.go) [tsc/internal/execute/tsc/init.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc/init.go)
- `tsc -b/--build` build mode parses a build command line (tsoptions.ParseBuildCommandLine) and runs build.NewOrchestrator over the project-reference graph. — [tsc/internal/execute/tsc.go#L53-120](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc.go#L53-L120) [tsc/internal/execute/build/orchestrator.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/build/orchestrator.go) [tsc/internal/tsoptions/parsedbuildcommandline.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/tsoptions/parsedbuildcommandline.go)
- Watch mode is created by createWatcher in internal/execute/watcher.go, layered on internal/execute/watchmanager and the vendored internal/fswatch backends. — [tsc/internal/execute/watcher.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/watcher.go) [tsc/internal/execute/watchmanager/watchmanager.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/watchmanager/watchmanager.go) [tsc/internal/fswatch/watcher_test.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/fswatch/watcher_test.go)
- Incremental compilation reads a prior .tsbuildinfo via incremental.ReadBuildInfoProgram, then wraps the new program with incremental.NewProgram to compute changes and reuse results; emit bookkeeping lives in emitfileshandler.go/snapshottobuildinfo.go. — [tsc/internal/execute/tsc.go#L287-343](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc.go#L287-L343) [tsc/internal/execute/incremental/program.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/incremental/program.go) [tsc/internal/execute/incremental/buildInfo.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/incremental/buildInfo.go)
- Diagnostics options --diagnostics/--extendedDiagnostics report phase timings and memory statistics (statistics.go), --generateTrace writes a trace file via internal/tracing, and --pprofDir starts CPU/heap profiling via internal/pprof. — [tsc/internal/execute/tsc/emit.go#L46-72](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc/emit.go#L46-L72) [tsc/internal/execute/tsc/statistics.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc/statistics.go) [tsc/internal/execute/tsc.go#L28-51](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc.go#L28-L51)
- The LSP server implements pull diagnostics (textDocument/diagnostic), hover, completion (+completionItem/resolve with auto-imports), definition/typeDefinition/sourceDefinition, references (incl. custom VS references), rename/prepareRename, workspace/willRenameFiles, formatting (document/range/on-type), codeAction, codeLens(+resolve), inlayHint, semanticTokens full/range, documentHighlight and a custom multiDocumentHighlight, foldingRange, selectionRange, linkedEditingRange, callHierarchy in/out, workspace/symbol, and VS autoInsert. — [tsc/internal/lsp/server.go#L1247-1297](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/server.go#L1247-L1297) [tsc/internal/ls/languageservice.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/ls/languageservice.go)
- Custom (non-standard) LSP methods are registered for logging ($/setLogVerbosity), developer profiling (runGC, saveHeapProfile, saveAllocProfile, startCPUProfile, stopCPUProfile), initializeAPISession, projectInfo, and setContentMapperContributions. — [tsc/internal/lsp/server.go#L1287-1297](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/server.go#L1287-L1297) [packages/vscode-typescript/package.json#L288-322](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/vscode-typescript/package.json#L288-L322)
- Automatic type acquisition (ATA) lives in internal/project/ata: it discovers typings (discovertypings.go, typesmap.go), validates package names, and installs npm packages through an injected ata.NpmExecutor implemented by the LSP server via exec `npm`. — [tsc/internal/project/ata/ata.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/project/ata/ata.go) [tsc/internal/project/ata/discovertypings.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/project/ata/discovertypings.go) [tsc/internal/project/ata/validatepackagename.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/project/ata/validatepackagename.go) [tsc/cmd/tsc/lsp.go#L59-63](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/cmd/tsc/lsp.go#L59-L63)
- Content mappers are a plugin mechanism: a tsconfig `contentMappers` entry names an npm package whose package.json declares Exec argv; the compiler spawns it as a child process speaking JSON-RPC (internal/ipc) to transform unsupported file types (e.g. .vue) into virtual TypeScript. — [tsc/internal/contentmapper/contentmapper.go#L1-52](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/contentmapper/contentmapper.go#L1-L52) [tsc/internal/contentmapper/hostimpl.go#L346-360](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/contentmapper/hostimpl.go#L346-L360) [tsc/internal/tsoptions/contentmappers.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/tsoptions/contentmappers.go)
- The IPC API exposes ~300 methods declared in internal/api/proto.go, including createSnapshot/updateSnapshot, createSourceFile, transpileModule/transpileDeclaration, parseConfigFile, getSymbolAtPosition, getTypeAtLocation, getSignaturesOfType, getSemanticDiagnostics/getSyntacticDiagnostics/etc., emit/emitToString, getJavaScriptEmit/getDeclarationEmit, intrinsic-type getters, and profiling controls. — [tsc/internal/api/proto.go#L57-140](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/api/proto.go#L57-L140) [tsc/internal/api/session.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/api/session.go)
- The npm package exposes the API under unstable exports: ./unstable/sync and ./unstable/async clients, ./unstable/fs (FS callbacks into the Go server), ./unstable/proto, and an AST toolkit (./unstable/ast with is/factory/scanner/visitor/clone subpaths). — [packages/typescript/package.json#L38-85](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/typescript/package.json#L38-L85) [packages/typescript/src/api/sync/client.ts](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/typescript/src/api/sync/client.ts) [packages/typescript/src/ast/ast.generated.ts](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/typescript/src/ast/ast.generated.ts)
- The VS Code extension contributes commands typescript.native-preview.{enable,disable,restart,output.focus,reportIssue,selectVersion,goToSourceDefinition,sortImports,removeUnusedImports,codeLens.showLocations} plus dev.* profiling commands, and settings like js/ts.trace.server, js/ts.server.pprofDir, js/ts.server.goMemLimit, js/ts.contentMappers.enabled. — [packages/vscode-typescript/package.json#L227-358](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/vscode-typescript/package.json#L227-L358)
- A transpile-only path exists: internal/transpile provides transpileModule support and the API exposes transpileModule/transpileDeclaration methods; the hidden fmtMain path in execute can format a file using internal/format. — [tsc/internal/transpile/transpile.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/transpile/transpile.go) [tsc/internal/api/proto.go#L71-74](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/api/proto.go#L71-L74) [tsc/internal/execute/tsc.go#L66-89](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc.go#L66-L89)
- tsc/CHANGES.md documents intentional behavior differences from the JS (Strada) compiler: trimmed JavaScript/JSDoc feature support (no Closure headers, no constructor expandos), removed options, and unified call-checking rules between .ts and .js. — [tsc/CHANGES.md](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/CHANGES.md)

## Data flow

For the CLI, input is argv -> tsoptions parsing (with ancestor tsconfig discovery and extended-config caching) -> a file loader that walks imports/type directives as parse tasks -> parser.ParseSourceFile producing ast.SourceFile trees -> binder-produced symbols -> a parallel checker pool producing diagnostics -> transformer chain -> printer/sourcemap emit through vfs.FS.WriteFile. For the LSP/API servers the same core is wrapped by internal/project: an immutable Snapshot owns a SnapshotFS overlay plus a ProjectCollection, and every edit/request produces a new snapshot; language-service operations read a snapshot's program. The API server adds a registry layer assigning stable SymbolID/TypeID/NodeHandle values that are encoded to MessagePack or JSON for the Node client.
- CLI input boundary: execute.CommandLine lower-cases argv[0] to detect -b/--build, then tsoptions.ParseCommandLine/ParseBuildCommandLine produce ParsedCommandLine values; tscCompilation locates tsconfig.json by walking ancestor directories via tspath.ForEachAncestorDirectory. — [tsc/internal/execute/tsc.go#L53-64](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc.go#L53-L64) [tsc/internal/execute/tsc.go#L269-281](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc.go#L269-L281) [tsc/internal/tsoptions/commandlineparser.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/tsoptions/commandlineparser.go)
- tsconfig parsing (GetParsedCommandLineOfConfigFile) resolves `extends` chains through an ExtendedConfigCache, merges command-line compilerOptions wrapped under a 'compilerOptions' key, and reports config parse errors as diagnostics before any compilation. — [tsc/internal/execute/tsc.go#L200-226](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc.go#L200-L226) [tsc/internal/tsoptions/tsconfigparsing.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/tsoptions/tsconfigparsing.go) [tsc/internal/execute/tsc/extendedconfigcache.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc/extendedconfigcache.go)
- File loading is a worklist of parseTask structs: each task loads a file via the compiler host, records module/type-reference resolutions in ModeAwareCache fields, and enqueues sub-tasks for discovered dependencies (filesparser.go/filesParser, fileloader.go). — [tsc/internal/compiler/filesparser.go#L17-55](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/compiler/filesparser.go#L17-L55) [tsc/internal/compiler/fileloader.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/compiler/fileloader.go) [tsc/internal/compiler/program.go#L289](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/compiler/program.go#L289)
- Module resolution is centralized in internal/module.Resolver with per-file mode-aware caches; resolved modules feed both the loader (which files to parse) and emit metadata (importHelpersImportSpecifier, jsxRuntimeImportSpecifier). — [tsc/internal/module/resolver.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/module/resolver.go) [tsc/internal/compiler/filesparser.go#L30-42](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/compiler/filesparser.go#L30-L42)
- Parse/bind/check/emit diagnostics flow through compiler.GetDiagnosticsOfAnyProgram; EmitFilesAndReportErrors calls GetBindDiagnostics and GetSemanticDiagnostics per file (timed against CompileTimes), then ProgramLike.Emit writes outputs via compiler.EmitOptions.WriteFile. — [tsc/internal/execute/tsc/emit.go#L74-140](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc/emit.go#L74-L140) [tsc/internal/compiler/emitter.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/compiler/emitter.go)
- Emit runs a transformer chain (internal/transformers: tstransforms type erasure/legacy decorators/metadata, moduletransforms commonjs/esmodule, estransforms for downlevel ES features, declarations for .d.ts) feeding internal/printer and internal/sourcemap. — [tsc/internal/transformers/transformer.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/transformers/transformer.go) [tsc/internal/transformers/chain.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/transformers/chain.go) [tsc/internal/transformers/declarations/transform.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/transformers/declarations/transform.go) [tsc/internal/printer/printer.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/printer/printer.go)
- Type checking is parallelized by a CheckerPool on the Program (compilerCheckerPool enables grouped parallel iteration and non-exclusive access for emit); ProgramOptions.CreateCheckerPool is injectable so the project system can supply its own pool. — [tsc/internal/compiler/program.go#L84-91](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/compiler/program.go#L84-L91) [tsc/internal/compiler/checkerpool.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/compiler/checkerpool.go) [tsc/internal/project/checkerpool.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/project/checkerpool.go)
- In the language server, state ownership is an immutable project.Snapshot: it holds a SnapshotFS (overlay of open-file contents over the base FS), a ProjectCollection, ConfigFileRegistry, AutoImports registry, and user preferences; each update clones forward the unchanged state. — [tsc/internal/project/snapshot.go#L26-46](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/project/snapshot.go#L26-L46) [tsc/internal/project/snapshotfs.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/project/snapshotfs.go) [tsc/internal/project/projectcollection.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/project/projectcollection.go)
- LSP request path: stdin bytes -> lsproto.BaseReader -> json.Unmarshal into lsproto.Message -> dynamic_queue requestQueue -> handleRequestOrNotification -> handlers() lookup -> for document requests, session.GetLanguageService(ctx, uri) resolves the project/snapshot, then ls.LanguageService methods compute results converted by internal/ls/lsconv. — [tsc/internal/lsp/server.go#L133-140](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/server.go#L133-L140) [tsc/internal/lsp/server.go#L1142-1192](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/server.go#L1142-L1192) [tsc/internal/lsp/server.go#L1341-1359](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/server.go#L1341-L1359) [tsc/internal/ls/lsconv/converters.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/ls/lsconv/converters.go)
- The API session assigns cross-process handles: symbols get IDs from a global atomic (ast.GetSymbolId) stored in a snapshot-wide symbolRegistry, while types and signatures get per-project registries keyed by project.ID to avoid ID collisions between checker pools. — [tsc/internal/api/session.go#L46-87](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/api/session.go#L46-L87)
- API transport: StdioServer.Run picks ipc.NewPipeTransport (PipePath) or NewStdioTransport, then wraps a session in either NewMessagePackProtocol+NewSyncConn or NewJSONRPCProtocol+NewAsyncConn depending on the --async flag. — [tsc/internal/api/server.go#L62-120](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/api/server.go#L62-L120) [tsc/internal/api/protocol_msgpack.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/api/protocol_msgpack.go) [tsc/internal/ipc/protocol_jsonrpc.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/ipc/protocol_jsonrpc.go)
- Node-side, the sync API client (packages/typescript/src/api/sync/client.ts) spawns the binary with getAPIProcessArgs, optionally enabling FS callbacks (--callbacks=...) so the Go server can call back into JS for readFile/fileExists/writeFile etc. via SyncRpcChannel. — [packages/typescript/src/api/sync/client.ts#L26-80](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/typescript/src/api/sync/client.ts#L26-L80) [tsc/internal/api/callbackfs.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/api/callbackfs.go) [tsc/cmd/tsc/api.go#L30-34](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/cmd/tsc/api.go#L30-L34)
- Content-mapped files enter the pipeline when the host returns content-mapped source files (GetContentMappedSourceFiles); ReuseProgram must re-run the external transform for such files and falls back to a full rebuild on failure. — [tsc/internal/compiler/program.go#L334-349](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/compiler/program.go#L334-L349) [tsc/internal/contentmapper/hostimpl.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/contentmapper/hostimpl.go)
- Output boundaries: diagnostics are rendered by tsc.CreateDiagnosticReporter to sys.Writer (stdout), emitted files go through vfs.FS.WriteFile, .tsbuildinfo is written by the incremental layer, and --diagnostics stats/printed lists go to the writer. — [tsc/internal/execute/tsc/diagnostics.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc/diagnostics.go) [tsc/internal/execute/tsc/emit.go#L115-140](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc/emit.go#L115-L140) [tsc/internal/execute/incremental/snapshottobuildinfo.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/incremental/snapshottobuildinfo.go)

## Behavior traces

Three flows were traced end to end. Batch compile: main -> runMain -> execute.CommandLine -> tscCompilation -> tsoptions parse/config discovery -> NewCachedFSCompilerHost -> compiler.NewProgram (processAllProgramFiles -> checker pool) -> EmitAndReportStatistics -> EmitFilesAndReportErrors (bind+check diagnostics, Emit) -> report + exit status. LSP: runLSP -> flag parse -> bundled.WrapFS(osvfs.FS()) -> lsp.NewServer -> Server.Run -> read/dispatch loop -> handlerMap -> project.Session snapshots -> ls.LanguageService. API: runAPI -> StdioServer.Run -> ipc transport accept -> StandaloneSession -> proto method table dispatch. A fourth flow covers watch/incremental rebuilds and a fifth covers VS Code extension activation.
- Startup (compile): main() -> runMain() -> core.ApplyDebugStackLimit() -> osutil.Args() -> execute.CommandLine(ctx, newSystem(), args, nil) -> os.Exit(result.Status); newSystem builds osSys with cwd, bundled.WrapFS(osvfs.FS()), bundled.LibPath(). — [tsc/cmd/tsc/main.go#L14-33](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/cmd/tsc/main.go#L14-L33) [tsc/cmd/tsc/sys.go#L124-138](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/cmd/tsc/sys.go#L124-L138)
- Compile flow order: CommandLine -> tscCompilation -> report early errors -> handle --init/--version/--help -> resolve configFileName (-p or findConfigFile ancestor walk) -> tsoptions.GetParsedCommandLineOfConfigFile -> CreateReportErrorSummary -> branch to watcher.start / performIncrementalCompilation / performCompilation. — [tsc/internal/execute/tsc.go#L122-267](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc.go#L122-L267)
- performCompilation: NewContentMapperHost (gated on RunExternalCode) -> compiler.NewCachedFSCompilerHost -> startTracingIfNeeded -> compiler.NewProgram -> tsc.EmitAndReportStatistics -> stopTracing -> CommandLineResult. — [tsc/internal/execute/tsc.go#L345-392](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc.go#L345-L392) [tsc/internal/execute/tsc/compile.go#L86-98](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc/compile.go#L86-L98)
- Inside NewProgram: processAllProgramFiles parses and resolves all root+dependency files (parse tasks -> fileLoader -> module.Resolver), then initCheckerPool, verifyCompilerOptions, collectContentMapperOptionDiagnostics. — [tsc/internal/compiler/program.go#L284-294](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/compiler/program.go#L284-L294) [tsc/internal/compiler/filesparser.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/compiler/filesparser.go)
- Emit path: EmitAndReportStatistics -> EmitFilesAndReportErrors -> GetDiagnosticsOfAnyProgram(ctx, programLike, ...) with per-file GetBindDiagnostics then GetSemanticDiagnostics -> programLike.Emit(EmitOptions{WriteFile}) -> SortAndDeduplicateDiagnostics -> ReportDiagnostic each -> listFiles -> ReportErrorSummary -> exit-status mapping (EmitSkipped+diagnostics => DiagnosticsPresent_OutputsSkipped). — [tsc/internal/execute/tsc/emit.go#L46-140](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc/emit.go#L46-L140)
- Incremental compile: performIncrementalCompilation reads oldProgram via incremental.ReadBuildInfoProgram(host) before parsing, then incremental.NewProgram(program, oldProgram, CreateHost(host), sys.Now, testing) computes the change set and EmitAndReportStatistics runs against the incremental program. — [tsc/internal/execute/tsc.go#L287-343](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc.go#L287-L343)
- LSP startup: `tsc --lsp --stdio` -> runLSP -> flag.Parse (--pprofDir, --clientProcessId; --pipe/--socket parsed but rejected, only stdio supported) -> bundled.WrapFS(osvfs.FS()), osvfs.GetGlobalTypingsCacheLocation() -> lsp.NewServer(ServerOptions{In,Out,Err,Cwd,FS,NpmInstall,Spawn,...}) -> s.Run(ctx). — [tsc/cmd/tsc/lsp.go#L20-74](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/cmd/tsc/lsp.go#L20-L74)
- LSP request handling: Server.Run reads messages into requestQueue; handleRequestOrNotification consults handlers()[req.Method]; document requests are wrapped by registerLanguageServiceDocumentRequestHandler which resolves session.GetLanguageService(ctx, params.TextDocumentURI()) and returns async work that runs the handler, then EnqueuePublishGlobalDiagnostics. — [tsc/internal/lsp/server.go#L1142-1192](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/server.go#L1142-L1192) [tsc/internal/lsp/server.go#L1341-1359](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/server.go#L1341-L1359)
- LSP lifecycle: initialize -> handleInitialize creates the project.Session (s.session set; requests before initialize get ErrorCodeServerNotInitialized via the register wrappers); shutdown -> handleShutdown; exit -> handleExit; a parent-process watchdog goroutine polls isProcessAlive(parentPID) every 5s and cancels the server context if the editor dies. — [tsc/internal/lsp/server.go#L1501](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/server.go#L1501) [tsc/internal/lsp/server.go#L1317-1339](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/server.go#L1317-L1339) [tsc/cmd/tsc/lsp.go#L95-115](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/cmd/tsc/lsp.go#L95-L115)
- API session startup: `tsc --api` -> runAPI -> parseAPIFlags (--cwd, --pipe, --callbacks, --async, --timing, --runExternalCode) -> api.NewStdioServer -> Run: create pipe or stdio transport -> bundled.WrapFS(osvfs.FS()) optionally wrapped by callbackFS -> project.SessionInit -> NewStandaloneSession -> transport.Accept -> protocol (msgpack sync or JSON-RPC async) -> conn serve loop. — [tsc/cmd/tsc/api.go#L41-82](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/cmd/tsc/api.go#L41-L82) [tsc/internal/api/server.go#L62-120](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/api/server.go#L62-L120)
- Watch flow: tscCompilation sees Watch.IsTrue() -> createWatcher(sys, config, commandLineOptions, raw, reporters, testing) -> watcher.start(ctx) -> returns CommandLineResult{Watcher: watcher}; watching is implemented over watchmanager which multiplexes fswatch backends. — [tsc/internal/execute/tsc.go#L233-244](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc.go#L233-L244) [tsc/internal/execute/watcher.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/watcher.go) [tsc/internal/execute/watchmanager/watchmanager.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/watchmanager/watchmanager.go)
- VS Code flow: extension activate() -> SessionManager.start -> getExe(context) resolves the tsgo binary -> client.start(exe) builds ServerOptions running `[exe, --lsp, ...pprofArgs]` with stdio transport -> NativePreviewLanguageClient (vscode-languageclient) connects; setContext 'typescript.native-preview.serverRunning' toggles command enablement. — [packages/vscode-typescript/src/extension.ts#L33-78](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/vscode-typescript/src/extension.ts#L33-L78) [packages/vscode-typescript/src/client.ts#L233-256](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/vscode-typescript/src/client.ts#L233-L256) [packages/vscode-typescript/src/session.ts#L207-224](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/vscode-typescript/src/session.ts#L207-L224)
- Program reuse on edit: Project updates call Program.UpdateProgram/ReuseProgram, which replaces only the changed SourceFile when safe and bails to a full NewProgram on redirect files, helper/JSX-runtime import requirements, or changed supplemental (content-mapped) files. — [tsc/internal/compiler/program.go#L296-403](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/compiler/program.go#L296-L403)

## Testing signals

Testing is Go-native (`go test ./...`, gotest.tools asserts) plus Node tests for the npm package and a bundled esbuild+node:test suite for the extension. The dominant signal is the baseline harness: internal/testrunner runs the ported Strada corpus under tsc/testdata/tests/cases (compiler/conformance/transpile, ~12.4k case files) and diffs outputs against tsc/testdata/baselines/reference, with `hereby baseline-accept` to promote. ~4,360 generated fourslash _test.go files exercise language-service features through an in-process LSP client; tsctests simulate the CLI including watch mode; the API and project/session layers have dedicated session tests. CI runs a large matrix: OS/arch (incl. Windows/Linux/macOS, arm64), race mode, noembed build tag, concurrent test programs, plus lint/format/generate/tidy/smoke jobs.
- internal/testrunner.CompilerBaselineRunner enumerates tsc/testdata/tests/cases/{compiler,conformance} for .ts/.tsx files and runs each as a baseline test; a TranspileRunner covers tests/cases/transpile; ~12,407 case files exist. — [tsc/internal/testrunner/compiler_runner.go#L36-76](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/testrunner/compiler_runner.go#L36-L76) [tsc/internal/testrunner/transpile_runner.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/testrunner/transpile_runner.go)
- Baselines compare generated output in tsc/testdata/baselines/local against tsc/testdata/baselines/reference and fail with 'Run `hereby baseline-accept` if the new baseline is correct'. — [tsc/internal/testutil/baseline/baseline.go#L26-84](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/testutil/baseline/baseline.go#L26-L84) [CONTRIBUTING.md#L128-138](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/CONTRIBUTING.md#L128-L138)
- A skippedTests list in compiler_runner.go excludes tests that depended on the JS codebase (APISample_* using typescript.d.ts) or removed options (verbatimModuleSyntax*, importsNotUsedAsValues*, noImplicitUseStrict*, etc.). — [tsc/internal/testrunner/compiler_runner.go#L78-120](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/testrunner/compiler_runner.go#L78-L120)
- Known divergences from the Strada baselines are tracked explicitly in tsc/testdata/submoduleAccepted.txt and submoduleTriaged.txt (per-file .diff lists), and promotedTestCollisions.txt. — [tsc/testdata/submoduleAccepted.txt](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/testdata/submoduleAccepted.txt) [tsc/testdata/submoduleTriaged.txt](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/testdata/submoduleTriaged.txt)
- Language-service behavior is tested by ~4,360 generated Go tests under tsc/internal/fourslash/tests driving a FourslashTest harness that runs an in-process LSPClient against a virtual FS (vfstest/iovfs) with marker/range annotations and state baselines. — [tsc/internal/fourslash/fourslash.go#L1-60](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/fourslash/fourslash.go#L1-L60) [tsc/internal/fourslash/tests/addAllMissingImportsNoCrash_test.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/fourslash/tests/addAllMissingImportsNoCrash_test.go)
- The CLI is tested end-to-end in internal/execute/tsctests (tsc_test.go, tscbuild_test.go, tscwatch_test.go, watcher_race_test.go) using a fake FS (fs.go) and mock watch backend (mock_watch_backend.go), with CommandLineTesting hooks (OnProgram, OnEmittedFiles) injected into execute. — [tsc/internal/execute/tsctests/runner.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsctests/runner.go) [tsc/internal/execute/tsctests/tscwatch_test.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsctests/tscwatch_test.go) [tsc/internal/execute/tsc.go#L53](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc.go#L53)
- Server-side coverage includes lsp server tests (server_test.go, server_completion_test.go, server_semantictokens_test.go, replay_test.go, stack_sanitizer_test.go), project/session tests (session_test.go, project_test.go, configfilechanges_test.go), api session tests (session_*_test.go), and unit tests scattered beside code (~4,548 _test.go files total in tsc/). — [tsc/internal/lsp/server_test.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/server_test.go) [tsc/internal/project/session_test.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/project/session_test.go) [tsc/internal/api/session_apistate_test.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/api/session_apistate_test.go)
- CI 'test' job runs `npx hereby test:tsc` and `test:benchmarks` on a matrix (ubuntu, windows, macos, linux-arm64, windows-arm64, race, noembed, concurrent-test-programs) with coverage uploaded to Codecov; baseline diffs are printed on failure and uploaded as artifacts. — [.github/workflows/ci.yml#L83-179](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/.github/workflows/ci.yml#L83-L179)
- CI 'go-test' job proves the tsc module builds and tests without Node.js (asserts `! command -v node`), and runs benchmarks once (`go test -run=- -bench=. -benchtime=1x ./...`). — [.github/workflows/ci.yml#L64-82](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/.github/workflows/ci.yml#L64-L82)
- Linting is `npx hereby lint` running golangci-lint with the tools/customlint plugin analyzers (e.g. forbidparentaccess, checkchildren, shadow) enforced in CI's lint job on ubuntu+windows and a noembed variant. — [tools/customlint/plugin.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tools/customlint/plugin.go) [.github/workflows/ci.yml#L237-274](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/.github/workflows/ci.yml#L237-L274) [CONTRIBUTING.md#L105](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/CONTRIBUTING.md#L105)
- Generated-code freshness is enforced: CI's 'generate' job runs `npx hereby generate` then fails on `git diff --staged --exit-code`; 'tidy' runs `go mod tidy -diff` on both modules plus `go work sync`. — [.github/workflows/ci.yml#L287-309](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/.github/workflows/ci.yml#L287-L309)
- A smoke job builds with --race and runs the built binary on tsc/testdata/fixtures/compiler with and without --singleThreaded. — [.github/workflows/ci.yml#L311-323](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/.github/workflows/ci.yml#L311-L323)
- Extension and npm-package tests are thinner: `npm run -w @typescript/typescript test` uses node --test over test/**/*.test.ts, and the extension test script compiles test/index.test.ts with esbuild and runs node --test on the bundle; CI runs these under test-extra (test:extension, test:tools, test:api, test:benchmarks:api). — [packages/typescript/package.json#L106-107](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/typescript/package.json#L106-L107) [packages/vscode-typescript/package.json#L373](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/vscode-typescript/package.json#L373) [.github/workflows/ci.yml#L223-227](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/.github/workflows/ci.yml#L223-L227)

## Risk map

The highest-risk surfaces are process spawning and protocol trust boundaries: the binary can exec arbitrary commands for content mappers (gated by --runExternalCode) and npm installs for ATA, and the --api server exposes the host filesystem (optionally piped through client callbacks) to whoever holds the pipe/stdio. Correctness risk concentrates in the baseline corpus: thousands of accepted diffs vs the JS compiler and an explicit skip list mean behavior parity is approximate, not exact. Platform-specific code (fswatch assembly FFI, per-OS process-alive checks) and panic-prone paths (NewServer panics on missing Cwd; per-request recover in handlers) are fragile spots. Generated files and the dual go.mod workspace create mechanical traps rather than runtime risk.
- osSys.Spawn/exec.Command is a raw process-execution boundary: spawnProcess launches command[0] with args, inheriting stderr; childProcess.Close kills and reaps the child. Used for content mappers and API-side spawning. — [tsc/cmd/tsc/sys.go#L68-122](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/cmd/tsc/sys.go#L68-L122)
- Content mappers execute arbitrary npm-package code declared in a project's tsconfig/package.json; execution is gated by the RunExternalCode option (--runExternalCode flag / js/ts.contentMappers.enabled setting) and NewContentMapperHost returns nil when disabled. — [tsc/internal/execute/tsc/compile.go#L86-98](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc/compile.go#L86-L98) [tsc/internal/contentmapper/contentmapper.go#L1-14](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/contentmapper/contentmapper.go#L1-L14) [tsc/cmd/tsc/api.go#L34](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/cmd/tsc/api.go#L34)
- ATA can shell out to `npm` (ServerOptions.NpmInstall runs exec.Command("npm", args...)); the LSP server implements ata.NpmExecutor, so a language server session can trigger package installation into the typings cache. — [tsc/cmd/tsc/lsp.go#L59-63](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/cmd/tsc/lsp.go#L59-L63) [tsc/internal/project/ata/ata.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/project/ata/ata.go) [tsc/internal/project/ata/installnpmpackages_test.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/project/ata/installnpmpackages_test.go)
- The --api server binds the host filesystem directly: StdioServer wraps bundled.WrapFS(osvfs.FS()) and optionally a callbackFS delegating readFile/fileExists/directoryExists/getAccessibleEntries/realpath to the client; a named-pipe/Unix-socket transport (PipePath) is an additional local attack surface. — [tsc/internal/api/server.go#L62-84](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/api/server.go#L62-L84) [tsc/internal/api/callbackfs.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/api/callbackfs.go) [tsc/internal/ipc/transport.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/ipc/transport.go)
- Thousands of behavior diffs vs the Strada compiler are accepted wholesale in submoduleAccepted.txt, and CHANGES.md documents deliberate feature removals (Closure JSDoc, constructor expandos, several options) — parity-sensitive consumers can hit silent behavioral differences. — [tsc/testdata/submoduleAccepted.txt](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/testdata/submoduleAccepted.txt) [tsc/CHANGES.md](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/CHANGES.md)
- The compiler-test skip list encodes known uncovered areas (all APISample_* tests and every test using removed options like verbatimModuleSyntax/importsNotUsedAsValues are skipped rather than ported). — [tsc/internal/testrunner/compiler_runner.go#L78-120](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/testrunner/compiler_runner.go#L78-L120)
- Platform-specific low-level code carries portability risk: fsevents_darwin_ffi_{amd64,arm64}.s hand-written assembly for FSEvents, isprocessalive_{unix,windows,other}.go for the LSP parent watchdog, and transport_{unix,windows}.go for pipes. — [tsc/internal/fswatch/fsevents_darwin_ffi_arm64.s](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/fswatch/fsevents_darwin_ffi_arm64.s) [tsc/cmd/tsc/isprocessalive_windows.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/cmd/tsc/isprocessalive_windows.go) [tsc/internal/ipc/transport_windows.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/ipc/transport_windows.go)
- Error-containment: NewServer panics when ServerOptions.Cwd is empty, and document-request handlers run under s.recover(req) so a checker crash is contained to the request; userFacingRequestFailedError distinguishes expected failures from logged errors. — [tsc/internal/lsp/server.go#L60-63](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/server.go#L60-L63) [tsc/internal/lsp/server.go#L1341-1359](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/server.go#L1341-L1359) [tsc/internal/lsp/stack_sanitizer.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/stack_sanitizer.go)
- contentMapperFallbackResponse silently returns empty/null LSP responses for unknown file types during the mapper-unregistration window — a deliberate correctness-for-availability trade that can mask real errors. (inferred) — [tsc/internal/lsp/server.go#L1194-1222](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/server.go#L1194-L1222)
- ReuseProgram's in-place file replacement has many bail-out conditions (redirect files, importHelpers/JSX-runtime imports, supplemental file shape); subtle misses here would produce stale-program bugs that only appear in long-running sessions and are hard to baseline-test. (inferred) — [tsc/internal/compiler/program.go#L323-403](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/compiler/program.go#L323-L403)
- The symbol/type handle layer in the API assumes binder symbol identity is stable snapshot-wide (global atomic IDs) but assigns types per-project; cross-project symbol queries depend on a first-writer-wins canonical project that could return subtly different results depending on call order. (inferred) — [tsc/internal/api/session.go#L46-87](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/api/session.go#L46-L87)
- Very large generated artifacts (lsproto/lsp_generated.go from the LSP meta-model, diagnostics_generated.go from diagnosticMessages.json, ast/factory/encoder generated files in the npm package) must be regenerated via hereby generate; hand edits are overwritten and CI fails on diffs. — [tsc/internal/lsp/lsproto/lsp_generated.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/lsproto/lsp_generated.go) [tsc/internal/diagnostics/generate.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/diagnostics/generate.go) [.github/workflows/ci.yml#L287-299](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/.github/workflows/ci.yml#L287-L299)
- Watch-mode correctness depends on debounce/coalescing in internal/fswatch (debounce.go) and watchmanager; watcher_race_test.go exists specifically because watch+rebuild had race conditions. (inferred) — [tsc/internal/fswatch/debounce.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/fswatch/debounce.go) [tsc/internal/execute/tsctests/watcher_race_test.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsctests/watcher_race_test.go) [tsc/internal/execute/watchmanager/watchmanager.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/watchmanager/watchmanager.go)
- The extension warns that tsserver plugins from other extensions will not be loaded under TypeScript 7 — an ecosystem-compat gap rather than a code bug, surfaced via warnAboutTsServerPlugins. — [packages/vscode-typescript/src/extension.ts#L173-266](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/vscode-typescript/src/extension.ts#L173-L266)

## Extension points

Extension happens at well-defined registries. New LSP methods plug into the handlers() map via registerRequestHandler/registerNotificationHandler/registerLanguageService*RequestHandler helpers, with protocol types generated from the LSP meta-model. New API methods add a Method constant plus an unmarshallerFor entry in proto.go and a handler on the session. The compiler is host-driven: vfs.FS, CompilerHost, CheckerPool, and contentmapper.Spawner are all injectable. Diagnostics, enums, AST kinds and localized strings are codegen'd from JSON/Go sources via hereby generate:* tasks. On the product side, tsconfig `contentMappers` is a user-facing plugin model, and the VS Code extension exposes registerContentMappers to other extensions.
- Adding an LSP method: implement a handleX on *Server (or a *ls.LanguageService method) and register it in handlers() inside server.go; the register* wrappers handle params unmarshalling, initialization gating, result sending, and async work. — [tsc/internal/lsp/server.go#L1227-1359](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/server.go#L1227-L1359)
- LSP protocol types are generated from the upstream meta-model: lsproto/_generate/fetchModel.mts downloads metaModel.json and generateLSP produces lsp_generated.go; custom methods are declared in lsproto/lsp.go (e.g. CustomSetLogVerbosityInfo, CustomTextDocumentSourceDefinitionInfo). — [Herebyfile.mjs#L558-567](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/Herebyfile.mjs#L558-L567) [tsc/internal/lsp/lsproto/lsp.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/lsproto/lsp.go) [tsc/internal/lsp/lsproto/lsp_generated.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/lsproto/lsp_generated.go)
- Adding an API method: declare a Method constant in proto.go, add its params unmarshaller to the method table (unmarshallerFor[T]), and implement the handler on the API session; clients call it through the sync/async Node clients. — [tsc/internal/api/proto.go#L57-140](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/api/proto.go#L57-L140) [tsc/internal/api/proto.go#L606-645](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/api/proto.go#L606-L645) [tsc/internal/api/session.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/api/session.go)
- File-system behavior is pluggable via the vfs.FS interface with existing implementations osvfs (real FS), wrapvfs, cachedvfs, iovfs, trackingvfs, vfsmock (moq-generated), and vfstest for tests. — [tsc/internal/vfs/vfs.go#L8-43](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/vfs/vfs.go#L8-L43) [tsc/internal/vfs/osvfs](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/vfs/osvfs) [Herebyfile.mjs#L524-526](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/Herebyfile.mjs#L524-L526)
- Compilation is host-injected: compiler.ProgramOptions takes a CompilerHost (NewCachedFSCompilerHost for CLI, compilerhost.go/projectreferencedtsfakinghost.go variants in the compiler and build packages), an optional CreateCheckerPool factory, TypingsLocation, and Tracing. — [tsc/internal/compiler/program.go#L37-49](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/compiler/program.go#L37-L49) [tsc/internal/compiler/host.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/compiler/host.go) [tsc/internal/execute/build/compilerHost.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/build/compilerHost.go)
- New diagnostics are added by editing diagnosticMessages.json/extraDiagnosticMessages.json and running `npx hereby generate:diagnostics`, which regenerates diagnostics_generated.go, loc stubs (loc_generated.go) and localized lcl payloads. — [tsc/internal/diagnostics/generate.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/diagnostics/generate.go) [Herebyfile.mjs#L487-499](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/Herebyfile.mjs#L487-L499) [tsc/internal/diagnostics/diagnosticMessages.json](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/diagnostics/diagnosticMessages.json)
- Enum/stringer codegen is declarative: //go:generate npx hereby generate:* directives in source files map to Herebyfile stringerGenerator/moqGenerator specs (e.g. generate:ast-stringer, generate:vfs, generate:projecttestutil). — [tsc/internal/bundled/bundled.go#L14](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/bundled/bundled.go#L14) [tsc/internal/vfs/vfs.go#L6](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/vfs/vfs.go#L6) [Herebyfile.mjs#L422-530](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/Herebyfile.mjs#L422-L530)
- Emit transforms plug in through the transformer chain (internal/transformers/chain.go): per-feature transformers live in tstransforms (type erasure, legacy decorators, metadata), estransforms (downlevel ES), moduletransforms (cjs/esm), and declarations for .d.ts emit. — [tsc/internal/transformers/chain.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/transformers/chain.go) [tsc/internal/transformers/tstransforms/typeeraser.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/transformers/tstransforms/typeeraser.go) [tsc/internal/transformers/moduletransforms/commonjsmodule.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/transformers/moduletransforms/commonjsmodule.go)
- Content mappers are the user-facing plugin point: tsconfig 'contentMappers' entries name npm packages whose package.json carries mapper metadata (Exec argv, declared compilerOptions, DynamicConfig); resolution lives in tsoptions/contentmappers.go. — [tsc/internal/contentmapper/contentmapper.go#L16-52](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/contentmapper/contentmapper.go#L16-L52) [tsc/internal/tsoptions/contentmappers.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/tsoptions/contentmappers.go)
- The VS Code extension exposes an ExtensionAPI to other extensions: onLanguageServerInitialized, initializeAPIConnection(pipe) and registerContentMappers(contributorId, contributions) which flow to the server's custom setContentMapperContributions method. — [packages/vscode-typescript/src/extension.ts#L27-31](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/vscode-typescript/src/extension.ts#L27-L31) [packages/vscode-typescript/src/contentMapperContributions.ts](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/vscode-typescript/src/contentMapperContributions.ts) [tsc/internal/lsp/server.go#L1296](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/server.go#L1296)
- project.Session is client-abstracted: project.Client and ata.NpmExecutor interfaces let the same session machinery serve the LSP server and the API server; test mocks are generated via moq into testutil/projecttestutil. — [tsc/internal/project/client.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/project/client.go) [tsc/internal/project/session.go#L84-96](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/project/session.go#L84-L96) [Herebyfile.mjs#L509-522](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/Herebyfile.mjs#L509-L522)
- The execute package is test-hooked through the tsc.CommandLineTesting interface (GetTrace, OnProgram, OnEmittedFiles, watch-status callbacks), letting tsctests intercept compilation internals without changing product code. — [tsc/internal/execute/tsc/compile.go#L80-83](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc/compile.go#L80-L83) [tsc/internal/execute/tsc.go#L53](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc.go#L53)
- Repo lint rules are extensible: adding an analyzer to BuildAnalyzers() in tools/customlint/plugin.go wires a new golangci-lint check for both Go modules. — [tools/customlint/plugin.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tools/customlint/plugin.go)

## Contributor handoff

Treat this as a Go repo with a Node-driven build. Read CONTRIBUTING.md first (Go 1.27, Node 24, `npm ci`, hereby commands), then Herebyfile.mjs for task wiring. For compiler changes the spine is cmd/tsc/main.go -> internal/execute/tsc.go -> internal/compiler/program.go; for server work it is internal/lsp/server.go (handlers map) + internal/project/session.go + internal/ls/*. Never edit *_generated.go / *.generated.ts files — change the generator inputs and run `npx hereby generate`. Verify with focused Go tests (`go -C ./tsc test -run 'TestLocal/<name>' ./internal/testrunner`), the baseline-accept workflow, and `npx hereby lint`/`format`/`tidy` before finishing.
- Environment: Go 1.27 (go.work with tsc/ and tools/ modules), Node >=22.18 / npm pinned via packageManager, `npm ci` then `npx hereby build`; built binary lands at built/local/tsc. — [CONTRIBUTING.md#L76-111](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/CONTRIBUTING.md#L76-L111) [go.work](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/go.work) [package.json#L6-8](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/package.json#L6-L8)
- Start by reading CONTRIBUTING.md 'Common tasks' and 'Compiler tests' sections — they document every hereby command and the focused-test invocation `go -C ./tsc test -run='TestLocal/<test name>' ./internal/testrunner`. — [CONTRIBUTING.md#L99-159](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/CONTRIBUTING.md#L99-L159)
- Files to read first for compiler work: tsc/cmd/tsc/main.go, tsc/internal/execute/tsc.go, tsc/internal/compiler/program.go, tsc/internal/compiler/filesparser.go, tsc/internal/checker/checker.go; for server work: tsc/internal/lsp/server.go, tsc/internal/project/session.go, tsc/internal/ls/languageservice.go. — [tsc/cmd/tsc/main.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/cmd/tsc/main.go) [tsc/internal/execute/tsc.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/execute/tsc.go) [tsc/internal/lsp/server.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/lsp/server.go)
- Generated code is pervasive and must not be hand-edited: *_generated.go files (stringer/moq/lsp/diagnostics outputs), packages/typescript/src/**/*.generated.ts, and bundled libs_generated.go; regenerate via `npx hereby generate` or the matching generate:* subtask; CI's generate job fails on any diff. — [Herebyfile.mjs#L347-535](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/Herebyfile.mjs#L347-L535) [.github/workflows/ci.yml#L287-299](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/.github/workflows/ci.yml#L287-L299) [CONTRIBUTING.md#L113-118](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/CONTRIBUTING.md#L113-L118)
- Compiler test cases are single .ts/.tsx files added under tsc/testdata/tests/cases/{compiler,conformance}; run them through the testrunner baseline harness and promote outputs with `npx hereby baseline-accept` into testdata/baselines/reference. — [CONTRIBUTING.md#L128-138](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/CONTRIBUTING.md#L128-L138) [tsc/internal/testrunner/compiler_runner.go#L58-76](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/testrunner/compiler_runner.go#L58-L76) [tsc/internal/testutil/baseline/baseline.go#L79](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/testutil/baseline/baseline.go#L79)
- Language-service features are tested by adding fourslash-style tests; existing tests under tsc/internal/fourslash/tests are generated files that drive an in-process LSP client against a virtual FS — follow their marker/range annotation conventions. — [tsc/internal/fourslash/fourslash.go#L44-60](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/fourslash/fourslash.go#L44-L60) [tsc/internal/fourslash/test_parser.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/fourslash/test_parser.go)
- Before submitting: run hereby generate, build, test, test:all, lint, format, check:format, the npm package build/test, extension build, `go mod tidy -diff` on both modules, `go work sync`, and verify `git diff --exit-code` — per CONTRIBUTING.md's checklist. — [CONTRIBUTING.md#L140-159](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/CONTRIBUTING.md#L140-L159)
- Formatting is dprint (Go via gofumpt plugin, plus TS/JSON/YAML) — `npx hereby format` / `check:format`; Go lint uses golangci-lint plus the repo's customlint analyzers, so patterns like parent access on nodes or unchecked type assertions may fail lint even when they compile. — [package.json#L27-34](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/package.json#L27-L34) [tools/customlint/plugin.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tools/customlint/plugin.go) [.github/workflows/ci.yml#L276-285](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/.github/workflows/ci.yml#L276-L285)
- The build intentionally passes -tags=noembed for local builds and CGO_ENABLED=0 (unless --race); the noembed build tag swaps bundled lib embedding for disk access — behavior differs between dev and release binaries. — [Herebyfile.mjs#L129-150](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/Herebyfile.mjs#L129-L150) [Herebyfile.mjs#L256-265](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/Herebyfile.mjs#L256-L265) [tsc/internal/bundled/bundled.go#L18-25](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/bundled/bundled.go#L18-L25)
- Editing shared kernel types (ast.Node, checker.Type) has huge blast radius: session handle registries, the node encoder index tables, and baseline baselines all depend on their invariants; the api/session.go comments document the symbol/type identity assumptions. (inferred) — [tsc/internal/api/session.go#L46-87](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/api/session.go#L46-L87) [tsc/internal/checker/types.go](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/internal/checker/types.go)
- Known trap: `--pipe` and `--socket` LSP flags are parsed but unsupported ('only stdio is supported'); likewise the sync API client throws for socket connections — don't assume those transports work end-to-end. — [tsc/cmd/tsc/lsp.go#L33-36](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/cmd/tsc/lsp.go#L33-L36) [packages/typescript/src/api/sync/client.ts#L29-31](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/packages/typescript/src/api/sync/client.ts#L29-L31)
- Do not add dependencies casually: tsc/go.mod has a deliberately tiny require list, and CI 'misc' runs checkmodpaths plus tidy checks on both modules. — [tsc/go.mod](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tsc/go.mod) [.github/workflows/ci.yml#L324-337](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/.github/workflows/ci.yml#L324-L337) [tools/cmd/checkmodpaths](https://github.com/microsoft/TypeScript/blob/5f6db9c9148635b4cbf72f1193b821b9c6b42dcc/tools/cmd/checkmodpaths)

Source repository: https://github.com/microsoft/TypeScript
Full evidence corpus: https://github.com/Codevetter/codevetter/tree/main/benchmarks/repo-unpacks/typescript.json

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)