Reference compiler — big map

The reference compiler is the best place to begin when a change affects the portable TypeRB language. It owns the complete path from source text to checked Go, Ruby, or TypeScript output.

Start with the executable trace and short code clinic. Read the change journey when you want responsibility and evidence that survive file moves. Use this page only when you need more exact source addresses for the version below.

Map version

This map describes TypeRB 0.4.3-dev at revision 8283239. Code links remain pinned to the full revision so that they keep showing the exact source described here. The concepts are meant to stay useful; exact filenames can move.

The central path

1. 1Load source and project
2. 2Lex and parse
3. 3Load declarations
4. 4Resolve names
5. 5Check types
6. 6Lower to typed IR
7. 7Generate Go, Ruby, or TypeScript

The shortest readable version of this pipeline lives in internal/compiler/compiler.go. Look for compileSourceUnit. It calls the major phases in order.

Code landmarks

Question	Start here	What you will find
How are characters grouped?	internal/lexer and internal/token	Lossless tokens, comments, and source spans
How is syntax recognized?	internal/parser	A handwritten recursive-descent parser, plus Pratt-style expression parsing
What shape does syntax use?	internal/ast	Declarations, statements, expressions, and their spans
Where do names connect?	internal/resolver	Module catalogs, imports, declarations, and name resolution
Where are types verified?	internal/checker	Expression types, calls, control flow, and type diagnostics
What crosses into code generation?	internal/lower and internal/ir	The checked program lowered into portable typed IR
How are targets produced?	internal/codegen	Shared generation entry and target-specific generators
How are errors represented?	internal/diagnostic	Stable codes, severity, messages, locations, and suggestions

Use this table as an index, not as a reading assignment. Open the row that answers your current question.

Three ways into the compiler

The central path is surrounded by three user-facing routes.

Command-line route

cmd/trb
  -> command and project loading
  -> compiler.CompileProject or compiler.AnalyzeProject
  -> diagnostics, generated source, or a target toolchain

Start at cmd/trb/main.go when you are tracing trb check, trb build, trb run, or trb test.

Editor route

editor request
  -> LSP
  -> compiler service snapshot
  -> compiler analysis
  -> language service answer

The important directories are internal/lsp, internal/compilerservice, and internal/languageservice. The editor asks questions about a compiler snapshot instead of compiling and running the project after every keystroke.

Tooling route

Formatting, linting, package installation, adapters, the REPL, and site tools reuse parts of the same language model. They are not extra compiler phases. Trace each tool inward until it reaches the shared parser, resolver, checker, or project analysis.

A useful reading order

For a first code-reading session:

1. Run the reference compiler trace.
2. Complete the 6 * 7 code clinic.
3. Read only compileSourceUnit in internal/compiler/compiler.go.
4. Use this map to open one neighboring construct relevant to your change.
5. Find its checker rule, IR node, and one affected target generator.

This follows one idea across boundaries. It is easier than reading one whole directory before you know what consumes it.

Where should a change go?

Desired change	Likely first area
New or changed syntax	lexer, parser, AST, formatter
Different name/import behavior	resolver and project loading
Different type rule	checker, then conformance tests
A portable execution behavior	IR, all affected backends, cross-backend tests
Better editor information	compiler service and language service, using shared analysis
Target-specific output correction	one code generator, while preserving portable behavior

If the change affects what TypeRB programs mean, write down the intended language behavior before treating it as a backend detail.