CodeVetter · Repo Unpack · Contributor handoff
microsoft/TypeScript
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.
- 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`.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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)
- 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.
- 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.