Fun facts

A few curiosities surfaced while exploring the TypeScript codebase.

The longest single source file is ~54,000 lines

src/compiler/checker.ts clocks in at 54,434 lines, almost 12% of all TypeScript source in the repository. By comparison, the second largest hand-written file (excluding generated lib.dom.d.ts) is src/compiler/utilities.ts at 12,447 lines. A typical workstation editor will visibly slow down opening it. The file is well-organised internally, but searching it usually involves jumping by section comments rather than scrolling.

The repo has its own ESLint rules

scripts/eslint/rules/ ships nine local rules implemented as CommonJS modules:

• argument-trivia — argument list whitespace.
• debug-assert — prefer Debug.assert* over Node's assert.
• js-extensions — enforce .js extensions in relative imports.
• jsdoc-format — well-formed JSDoc comments.
• no-array-mutating-method-expressions — flags arr.sort() / arr.reverse() as expressions.
• no-direct-import — forbids importing sibling files outside the _namespaces/ barrel.
• no-in-operator — disallows in for property tests on prototype-less maps.
• no-keywords — disallow accidental use of reserved keywords as identifier names.
• only-arrow-functions — discourage function expressions where this semantics would surprise.

The compiler is its own dogfood — these rules guard against regressions that the team has hit in real review.

Scanner produces tokens for >, >>, >>>, <, <=, => and JSX

scanner.ts is shared between TypeScript and JSX/TSX/JSDoc parsing, switching modes via flags. Several token kinds (BacktickToken, HashToken) are produced only by the JSDoc scanner; the regular scanner produces NoSubstitutionTemplateLiteral and PrivateIdentifier instead. The relevant jsdoc remarks live right next to the SyntaxKind declarations in src/compiler/types.ts.

Branded types

The compiler uses TypeScript-only "branded" string types liberally:

export type Path = string & { __pathBrand: any };
export type __String = string & { __escapedIdentifier: void };

These have no runtime cost but make it impossible to confuse, e.g., a raw string filename with a normalised Path key. Searching the code for __Brand reveals dozens of similar markers.

The repo's first commit is a code drop

Commit 99ec3a96… on 2014-07-07 is titled "Add snapshot of compiler sources". This is the moment TypeScript moved from a private repository into the public one we have today; the C#-then-TS-bootstrapped pre-history isn't here.

The longest-lived TODO comments are in checker.ts

There are 59 TODO/FIXME/HACK comments in checker.ts alone (out of 468 total in src/). Several TODO: GH#NNNN comments link to GitHub issues that are still open. The pattern of "we know this is a corner, here's the issue" is part of the file's culture.

"Hereby"

The build runner is named hereby and the build file is Herebyfile.mjs. It's a successor to the team's earlier gulpfile. The build does still expose a npm run gulp alias that just calls hereby. See package.json.

TypeScript ships its own DOM .d.ts — but doesn't write it

src/lib/dom.generated.d.ts is 45,109 lines, larger than every hand-written compiler file except checker.ts. It and its sibling webworker.generated.d.ts are generated — modifications must be made upstream at microsoft/TSJS-lib-generator, which scrapes WebIDL and the spec sources.

The reason to read AGENTS.md

The README, CONTRIBUTING, AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md all begin with the same instruction: read AGENTS.md before writing code. That's because the repository is in maintenance mode and nearly every kind of PR should now go to microsoft/typescript-go. The redundancy is intentional — different agents inspect different files first.