|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +TypeScript 7 is a native port of the TypeScript compiler and language server written in Go. This is a work-in-progress project that aims to achieve feature parity with TypeScript 5.8, with most development happening in the `internal` directory. |
| 8 | + |
| 9 | +## Build System and Commands |
| 10 | + |
| 11 | +This project uses `hereby` as the primary build tool. The following npm scripts are available: |
| 12 | + |
| 13 | +```bash |
| 14 | +# Core build and test commands |
| 15 | +npm run build # Build the tsgo binary using hereby |
| 16 | +npm run build:watch # Build with watch mode |
| 17 | +npm run build:watch:debug # Build with debug output in watch mode |
| 18 | +npm run test # Run all tests |
| 19 | + |
| 20 | +# Package-specific commands |
| 21 | +npm run api:build # Build the API package |
| 22 | +npm run extension:build # Build the VS Code extension |
| 23 | +npm run extension:watch # Build extension in watch mode |
| 24 | + |
| 25 | +# Development utilities |
| 26 | +npm run node # Run node with special conditions |
| 27 | +npm run convertfourslash # Convert fourslash test files |
| 28 | +npm run updatefailing # Update failing test baselines |
| 29 | +npm run makemanual # Create manual test files |
| 30 | +``` |
| 31 | + |
| 32 | +Additional hereby commands (run with `npx hereby <command>`): |
| 33 | +- `npx hereby format` - Format the code using dprint |
| 34 | +- `npx hereby lint` - Run Go linters |
| 35 | +- `npx hereby baseline-accept` - Update test baselines/snapshots |
| 36 | + |
| 37 | +### Build Options |
| 38 | + |
| 39 | +The build system supports several flags for debugging and performance analysis: |
| 40 | +- `--debug` - Include debug symbols and disable optimizations |
| 41 | +- `--race` - Enable Go race detector (use `TSGO_HEREBY_RACE=true`) |
| 42 | +- Build tags: `release` (default), `noembed` for debugging |
| 43 | + |
| 44 | +## Testing |
| 45 | + |
| 46 | +### Running Specific Tests |
| 47 | + |
| 48 | +```bash |
| 49 | +# For pre-existing "submodule" tests from _submodules/TypeScript |
| 50 | +go test -run='TestSubmodule/<test name>' ./internal/testrunner |
| 51 | + |
| 52 | +# For new "local" tests in testdata/tests/cases |
| 53 | +go test -run='TestLocal/<test name>' ./internal/testrunner |
| 54 | + |
| 55 | +# Run tests with race detection (for debugging concurrency issues) |
| 56 | +go test -race ./internal/testrunner |
| 57 | + |
| 58 | +# Run tests for a specific package (e.g., parser, checker, etc.) |
| 59 | +go test ./internal/parser |
| 60 | +go test ./internal/checker |
| 61 | +``` |
| 62 | + |
| 63 | +### Writing New Compiler Tests |
| 64 | + |
| 65 | +New compiler tests go in `testdata/tests/cases/compiler/` and use TypeScript syntax with special comments: |
| 66 | + |
| 67 | +```ts |
| 68 | +// @target: esnext |
| 69 | +// @module: preserve |
| 70 | +// @moduleResolution: bundler |
| 71 | +// @strict: true |
| 72 | +// @checkJs: true |
| 73 | + |
| 74 | +// @filename: fileA.ts |
| 75 | +export interface Person { |
| 76 | + name: string; |
| 77 | + age: number; |
| 78 | +} |
| 79 | + |
| 80 | +// @filename: fileB.js |
| 81 | +/** @import { Person } from "./fileA" */ |
| 82 | +function greet(person) { |
| 83 | + console.log(`Hello, ${person.name}!`); |
| 84 | +} |
| 85 | +``` |
| 86 | + |
| 87 | +**Always enable strict mode (`@strict: true`) unless testing non-strict behavior.** |
| 88 | + |
| 89 | +Test outputs are generated in `testdata/baselines/local` and compared against `testdata/baselines/reference`. Use `npx hereby baseline-accept` to update baselines after test changes. |
| 90 | + |
| 91 | +## Architecture |
| 92 | + |
| 93 | +### Key Directories |
| 94 | + |
| 95 | +- **`internal/`** - Main compiler and language server code (Go) |
| 96 | + - `compiler/` - Core compilation logic |
| 97 | + - `parser/` - TypeScript parsing |
| 98 | + - `checker/` - Type checking |
| 99 | + - `binder/` - Symbol binding |
| 100 | + - `scanner/` - Lexical analysis |
| 101 | + - `lsp/` - Language Server Protocol implementation |
| 102 | + - `testrunner/` - Test execution framework |
| 103 | +- **`_extension/`** - VS Code extension (TypeScript/JavaScript) |
| 104 | +- **`_packages/`** - NPM packages |
| 105 | + - `native-preview/` - Preview npm package |
| 106 | + - `api/` - TypeScript API bindings |
| 107 | +- **`_submodules/TypeScript`** - Reference TypeScript implementation |
| 108 | +- **`testdata/`** - Test cases and baselines |
| 109 | + |
| 110 | +### Development Workflow |
| 111 | + |
| 112 | +1. Write minimal test cases demonstrating the bug/feature |
| 113 | +2. Run tests to verify failure (bugs) or expected behavior (features) |
| 114 | +3. Accept generated baselines if needed |
| 115 | +4. Implement the fix/feature in `internal/` |
| 116 | +5. Re-run tests and accept new baselines |
| 117 | +6. Ensure code is formatted (`npx hereby format`) and linted (`npx hereby lint`) |
| 118 | + |
| 119 | +### Code Reference |
| 120 | + |
| 121 | +The `internal/` directory is ported from `_submodules/TypeScript`. When implementing features or fixing bugs, search the TypeScript submodule for reference implementations. |
| 122 | + |
| 123 | +## Language Server Integration |
| 124 | + |
| 125 | +The LSP implementation is in `internal/lsp/`. Editor functionality requires integration testing with the language server, not just compiler tests. |
| 126 | + |
| 127 | +## Go Development Notes |
| 128 | + |
| 129 | +### Module Structure |
| 130 | +- Uses Go 1.25+ with workspace mode |
| 131 | +- Main module: `github.com/microsoft/typescript-go` |
| 132 | +- Key dependencies: `regexp2`, `go-json-experiment/json`, `xxh3` for hashing |
| 133 | +- Build tools included as Go tools: `moq`, `stringer`, `gofumpt` |
| 134 | + |
| 135 | +### Performance Considerations |
| 136 | +- UTF-8 string handling differs from TypeScript's UTF-16 approach |
| 137 | +- Node positions use UTF-8 offsets, not UTF-16 (affects non-ASCII character positions) |
| 138 | +- xxh3 hashing used for performance-critical operations |
| 139 | +- Memory pooling and string interning used in hot paths |
| 140 | + |
| 141 | +### Debugging |
| 142 | +- Use `--debug` flag for builds to include debug symbols |
| 143 | +- Race detector available with `--race` or `TSGO_HEREBY_RACE=true` |
| 144 | +- LSP debugging can be enabled through VS Code extension settings |
| 145 | + |
| 146 | +## Intentional Changes |
| 147 | + |
| 148 | +See `CHANGES.md` for documented differences between this Go port and the original TypeScript compiler, including scanner, parser, and JSDoc handling changes. |
0 commit comments