Why Not Put Everything in One Place?

The obvious question: why not put all IDE features in the LSP server? Or all of them in the plugin?

Everything in the LSP sounds right until you type a character. The LSP server runs the full GALA transpilation pipeline -- parse, analyze, transform -- to produce type information. That pipeline takes tens to hundreds of milliseconds depending on file size and import graph depth. Syntax highlighting, brace matching, and code folding need to respond in under 5ms or the editor feels broken. You cannot debounce syntax highlighting. It has to be synchronous and local.

Everything in the plugin sounds right until you need types. The IntelliJ plugin has a PSI tree built from the ANTLR grammar. It knows the structure of the code -- where functions are, where braces match, what tokens are keywords. But it has no idea what type x is in val x = people.Map((p) => p.Name). That requires running the analyzer, resolving imports across packages, and executing the transformer's type inference. Reimplementing that in Kotlin would mean maintaining two type systems, and the transpiler's type system is the only one that matters because it produces the Go output.

So the split is forced by latency on one side and semantic depth on the other.

What the Plugin Owns

The plugin handles everything that can be answered by looking at tokens and the local PSI tree, without running the transpiler.

Syntax highlighting. The ANTLR grammar generates a Java lexer (Bazel patches -> skip to -> channel(HIDDEN) so whitespace tokens survive for the IDE). GalaSyntaxHighlighter.kt maps token types to IntelliJ's text attribute keys -- keywords get one color, string literals another, comments another. This is pure token classification; no parsing required.

Brace matching. Parentheses, braces, brackets. The plugin registers GalaBraceMatcher and IntelliJ handles the rest. Zero network calls.

Code folding. GalaFoldingBuilder.kt walks the PSI tree looking for block nodes (function bodies, sealed type declarations, import groups) and registers foldable regions. This is structural, not semantic -- you don't need to know what a function returns to know where its body ends.

Structure view. GalaStructureViewElement.kt extracts top-level declarations from the PSI tree -- functions, types, sealed types with their cases, vals, vars. This powers the sidebar outline and Ctrl+F12 navigation. Again, purely structural.

Keyword and basic completion. GalaCompletionContributor.kt offers keyword completions (val, func, match, sealed) and built-in type names (int, string, bool, Option, Either). These are hardcoded lists. They respond instantly because there is nothing to compute.

Live templates. Snippet expansion for common patterns. Local, instant, no server involved.

The common trait: all of these features are fast because they operate on data the plugin already has. No IPC, no analysis, no waiting.

What the LSP Server Owns

The LSP server handles everything that requires the transpiler's semantic model. The GalaHandler in server.go wraps the full pipeline: ANTLR parser, analyzer, and transformer.

Diagnostics. On every edit, the server runs analyzeFile -- parse the source, run the analyzer to resolve imports and build the RichAST, then run the transformer via TransformForLSP to catch type errors. Parse errors, semantic errors, and match exhaustiveness warnings all flow back as LSP diagnostics. The server uses a cancel-and-restart pattern with a 300ms debounce: each keystroke cancels any in-flight analysis and starts a new timer. Before publishing, it checks the document version to discard stale results. Old diagnostics stay visible until replaced -- no flicker.

Type-aware completion. When the user types a dot, completion.go resolves the receiver's type using the cached RichAST and the transformer's VarTypes map. If you type person., the server looks up the type of person, finds its methods and fields in richAST.Types, and returns them. This is qualitatively different from the plugin's keyword completion -- it knows that person is a Person struct with a Name field and an Age field. It also handles package-qualified dot completion (collection_immutable.Array), named argument completion inside constructors (Person(Name =), and match case completion with field destructuring for sealed types.

Inlay hints. For val x = someExpression, the server resolves the type of someExpression through the transformer and displays the inferred type inline. This requires the full type inference pipeline.

Hover. Ctrl+Q shows type signatures, struct fields, method lists, and sealed type variants. All sourced from the RichAST.

Go-to-definition. Cross-file navigation using the analyzer's resolved metadata. The plugin's PSI tree only knows about the current file; the analyzer knows the entire package graph.

The Sync Problem

Here is where it gets uncomfortable. The plugin has hardcoded lists:

// GalaCompletionContributor.kt
val DECLARATION_KEYWORDS = listOf("val", "var", "func", "type", "struct", ...)
val BUILTIN_TYPES = listOf("int", "string", "bool", "float64", "Option", "Either", ...)

The LSP server has its own list:

// completion.go
keywords := []string{
    "package", "import", "val", "var", "func", "type", "struct",
    "interface", "sealed", "embed", "if", "else", "for", "range",
    "return", "match", "case", "true", "false", "nil", "map",
}

And the actual source of truth is neither of these -- it is the ANTLR grammar (gala.g4) for keywords and types.go's IsPrimitiveType() for built-in types.

If someone adds a keyword to the grammar and forgets to update the plugin, keyword completion silently omits it. If someone adds a built-in type to the transpiler and forgets to update the syntax highlighter, that type name renders in the wrong color. These bugs are subtle, they don't cause test failures, and they erode trust in the tooling.

SYNC.md as a Contract

GALA's answer is a synchronization document (ide/intellij/SYNC.md) that explicitly lists every hardcoded data point, its authoritative source, and how to extract the current values. Nine sync points are documented:

1. Keywords -- plugin completion lists and highlighter vs. gala.g4 lexer rules
2. Built-in types -- plugin annotator, highlighter, and completion vs. types.go
3. Std auto-imported types -- plugin completion vs. std/*.gala sealed types
4. Std methods -- plugin postfix templates vs. std/*.gala method definitions
5. Importable package types -- explicitly marked as NOT in static lists (LSP-only)
6. Highlighter token mapping -- plugin when block vs. generated Java lexer constants
7. LSP completion keywords -- completion.go vs. gala.g4
8. LSP type inference -- inlay_hints.go vs. transpiler type system
9. LSP match exhaustiveness -- reads from RichAST at runtime (no hardcoded data)

Each entry includes the exact file paths and shell commands to extract current values. The document also specifies trigger conditions: sync after any grammar change, new std type, new collection type, or built-in type change.

This is not automated enforcement -- it is a documented contract. When you change the grammar, you know exactly which files to update because the document tells you. It trades perfection for pragmatism: a grep command you can run is more useful than a validation framework nobody maintains.

Trade-offs in Practice

Latency. The plugin responds in under 5ms for highlighting, folding, brace matching, and keyword completion. The LSP server debounces at 300ms and analysis can take longer. Users see instant syntax feedback but slightly delayed error squiggles. This is the right trade-off -- laggy highlighting is unacceptable, laggy diagnostics are tolerable.

Accuracy. The plugin's keyword completion will suggest match whether or not you are in a context where match is valid. The LSP server's type-aware completion will only suggest methods that actually exist on the receiver's type. Local is approximate; semantic is precise.

Portability. The IntelliJ plugin works only in JetBrains IDEs. The LSP server works in VS Code, Neovim, Helix -- anything that speaks LSP 3.17 over stdio. If GALA only had the plugin, two-thirds of potential users would have no IDE support. The LSP server is the portable foundation; the plugin is the premium layer for JetBrains users.

Maintenance cost. Two codebases in two languages (Kotlin and Go) with shared assumptions. Every grammar change touches both. The SYNC.md contract reduces the risk but does not eliminate it. This is the real cost of the split architecture, and it is worth paying because the alternative -- reimplementing type inference in Kotlin or accepting 300ms syntax highlighting latency -- is worse.

The Uncomfortable Truth

A two-process architecture is not elegant. It is a pragmatic response to competing constraints: the plugin must be fast, the server must be smart, and neither can do the other's job well. The synchronization contract is a maintenance burden that scales linearly with language complexity. Every new keyword, every new built-in type, every new sealed variant in std is a potential sync failure.

But the alternative architectures are worse. A pure-LSP approach makes the editor feel sluggish. A pure-plugin approach cannot provide semantic features without reimplementing the transpiler. A single-binary approach that embeds the transpiler in a JetBrains plugin locks out every other editor.

The split is the least bad option. SYNC.md is the acknowledgment that it has costs. And the 300ms debounce in DidChange is the number that makes it all work -- fast enough to feel responsive, slow enough to avoid burning CPU on every keystroke.

This post is about how we fake it.

The completion cascade

Before resolving any types, the handler needs to figure out what kind of completion the user wants. GALA's completion handler runs a context detection cascade -- four checks in priority order:

isDot := isDotCompletion(text, line, char)

if isDot && richAST != nil {
    receiverType := typeAtDot(text, line, char, richAST, varTypeMap)
    if strings.HasPrefix(receiverType, packagePrefix) {
        pkgName := strings.TrimPrefix(receiverType, packagePrefix)
        items = append(items, packageCompletions(richAST, pkgName)...)
    } else if receiverType != "" {
        items = append(items, typeSpecificCompletions(richAST, receiverType)...)
    }
} else if isNamedArgContext(text, line, char) && richAST != nil {
    // Constructor named args: Person(name = ...)
} else if isMatchCaseContext(text, line, char) && richAST != nil {
    // Sealed type case suggestions
} else {
    // Global: types, functions, keywords
}

Dot completion wins. If it fires, nothing else runs. This matters because a dot inside a constructor call (Person(address = city.) is both a named-arg context and a dot context. The dot takes priority because the user is actively accessing a member.

Detecting the dot

isDotCompletion does something deceptively simple: it walks backwards from the cursor position on the current line, looking for a . character. But there's a subtlety. When the user types order.ge, the cursor is after e, not after .. The partial identifier ge is what they've typed so far. We need to skip past it:

func isDotCompletion(text string, line, char int) bool {
    // ...
    if l[char-1] == '.' {
        return true
    }
    // Walk backwards past any partial identifier being typed
    i := char - 1
    for i >= 0 && isIdentChar(l[i]) {
        i--
    }
    if i >= 0 && l[i] == '.' {
        return true
    }
    return false
}

This handles both order. (cursor right after dot) and order.ge (cursor mid-identifier after dot). The partial identifier is irrelevant for type resolution -- we only care about what's to the left of the dot.

Resolving the receiver type

This is where things get interesting. typeAtDot needs to figure out what type order is. It has no type checker, no symbol table built from a full program analysis. What it has:

1. VarTypes -- a map[string]string populated by the transpiler during its last successful transform. Keys are scoped: "main.order" maps to "Order", "processItems.item" maps to "Item". The transpiler already resolved these types while generating Go code; we just reuse its work.

2. RichAST -- the transpiler's analysis output containing type metadata (fields, methods, sealed variants), function signatures, package information, and import aliases.

The resolution cascade in resolveReceiverType tries five strategies in order:

func resolveReceiverType(name, funcScope string, richAST *transpiler.RichAST,
    varTypes map[string]string) string {
    // 1. Transpiler's resolved var types (function-scoped)
    if typStr := lookupVarType(varTypes, funcScope, name); typStr != "" {
        return stripTypeParams(typStr)
    }
    // 2. Function call return type: GetOrder() → Order
    if fm, ok := richAST.Functions[name]; ok { ... }
    // 3. Sealed case constructor → parent type: Some(42) → Option
    for _, tm := range richAST.Types { ... }
    // 4. Package name → package marker
    for _, pkgName := range richAST.Packages { ... }
    // 5. Type name for static calls: List.Empty()
    if isExported(name) { if findType(richAST, name) != nil { return name } }
    return ""
}

The scoped lookup is important. lookupVarType tries funcScope + "." + varName first, then falls back to an unscoped lookup. If you have a val order = ... inside func main, it's stored as "main.order". The enclosing function is found by scanning backwards from the cursor for a func declaration -- crude, but effective for GALA's single-function-per-block structure.

The chain problem

Simple variable access is easy. The hard case is chains: collection.Map(transform).Filter(predicate).. The user expects completions for whatever Filter returns, which means we need to resolve the entire chain left-to-right.

typeAtDot handles this by detecting a closing paren before the dot. When it sees ), it walks backwards through balanced parentheses to find the method name, then checks if there's another dot before that name -- indicating a chain:

// Case 1: Closing paren before dot — expr.Method().
if i >= 0 && l[i] == ')' {
    depth := 1
    i--
    for i >= 0 && depth > 0 {
        if l[i] == ')' { depth++ }
        else if l[i] == '(' { depth-- }
        i--
    }
    // Extract the method name before '('
    name := l[nameStart:nameEnd]
    if i >= 0 && l[i] == '.' {
        // Chained: resolve receiver, then get method's return type
        receiverType := resolveChainType(l[:i], enclosingFunc, richAST, varTypes)
        if receiverType != "" {
            return resolveMethodReturn(richAST, receiverType, name)
        }
    }
}

resolveChainType is recursive. It peels off the rightmost segment of the expression, resolves its type, then uses resolveMethodReturn to look up what that method returns on that type. A depth limit of 10 prevents infinite recursion on pathological inputs:

const maxChainDepth = 10

func resolveChainTypeN(text string, funcScope string, richAST *transpiler.RichAST,
    varTypes map[string]string, depth int) string {
    if depth > maxChainDepth { return "" }
    // ...
    if text[len(text)-1] == ')' {
        // Walk balanced parens, extract method name
        if i >= 0 && text[i] == '.' {
            receiverType := resolveChainTypeN(text[:i], funcScope, richAST, varTypes, depth+1)
            if receiverType != "" {
                return resolveMethodReturn(richAST, receiverType, methodName)
            }
        }
    }
    // Plain identifier — resolve directly
    return resolveReceiverType(name, funcScope, richAST, varTypes)
}

So for collection.Map(transform).Filter(predicate)., resolution proceeds: resolve collection from VarTypes (say, List), look up Map's return type on List (say, List), look up Filter's return type on List (say, List), then show List's methods.

There's an obvious limitation: generic type parameters are erased. stripTypeParams drops [T] from List[int] before lookup, so collection.Map(toStr). still shows List methods, not List[string] methods. The method set is the same either way for GALA's standard library types, so this works in practice. It wouldn't work for a language where different type parameters produce different method sets.

The __package__ hack

When the user types http., they're not accessing a field on a variable -- they want the exports of the http package. But the resolution cascade would happily try to find a variable called http in VarTypes, fail, and return nothing.

The fix is a sentinel value. resolveReceiverType checks the RichAST's package list and import aliases. If the name matches a known package, it returns "__package__:http" instead of a type name:

const packagePrefix = "__package__:"

// In resolveReceiverType:
for _, pkgName := range richAST.Packages {
    if pkgName == name {
        return packagePrefix + name
    }
}
if richAST.ImportAliases != nil {
    if pkgName, ok := richAST.ImportAliases[name]; ok {
        return packagePrefix + pkgName
    }
}

Back in the completion handler, this prefix triggers a completely different code path -- packageCompletions instead of typeSpecificCompletions. Package completions pull from three sources: types belonging to that package, functions belonging to that package, and GoExports (a map of raw export names from Go-only packages that the transpiler has seen but not fully analyzed).

The alias handling matters. If the GALA source has import io = "collection/immutable", typing io. needs to resolve the alias io to the actual package name collection/immutable and show its exports.

Generating completions

Once we have a resolved type name, typeSpecificCompletions looks it up in the RichAST via findType and builds completion items from three sources:

Methods get full signatures and smart insert text. Zero-parameter methods insert () immediately; methods with parameters insert ( and let the editor handle the rest (which sets up signature help):

if len(m.ParamNames) == 0 {
    insertText = name + "()"
} else {
    insertText = name + "("
}

Fields show their type as the detail string. Sealed variants generate IsXxx() predicate methods. And every type gets a match keyword suggestion, because pattern matching is idiomatic in GALA.

findType itself is more resilient than you'd expect. It tries direct key lookup, std.-prefixed lookup (GALA's standard library), qualified-name decomposition (mylib.Animal matches a type with simple name Animal), and type alias resolution. This layered lookup handles the fact that the RichAST keys aren't always consistent -- sometimes they're package-qualified, sometimes they're not, depending on how the type was declared.

Edge cases: cursor position semantics

Different editors report cursor positions differently when the user triggers completion on a dot. Some place the cursor on the dot (before it), others place it after the dot. VS Code places it after, which is what isDotCompletion checks first (l[char-1] == '.'). But when the user has typed order.ge and triggers completion mid-word, the cursor is past both the dot and the partial identifier. The backwards walk through isIdentChar handles this uniformly.

There's also the question of what happens when the dot is at column 0 (nothing before it) or when the line itself is shorter than the reported cursor position. Both are guarded: char <= 0 returns early, and char is clamped to len(l) to handle editors that report positions beyond line length.

What we're actually doing

The core insight is that we never build a type checker. We mooch off the transpiler. Every time the document changes, the LSP runs TransformForLSP, which does a partial transpilation and dumps its resolved variable types into a flat map. The LSP's job is just text surgery -- walk backwards from the cursor, figure out what syntactic construct we're in, and look up the answer in pre-computed tables.

It's fragile in ways a real type checker wouldn't be. Chains longer than what the transpiler resolved break. Generic type parameters are erased. Completions after a syntax error on the same line might fail because the backwards paren-walk gets confused. But it's fast, it handles the common cases, and it was built in a fraction of the time a real type checker would take.

Sometimes the right engineering decision is to not build the thing you think you need.

GALA transpiles to Go. When a user writes val x = Some(42) in their editor, the LSP needs to know that x is Option[int]. But there's no Go source file to analyze yet -- the transpiler hasn't run. And even after it runs, the generated Go uses different names, wraps values in Immutable[T], and structures code in ways that don't map cleanly back to the original source positions. This is the type information gap, and every transpiled language has to solve it.

The naive approach: running go/types on the output

The first thing you'd try -- and the first thing we tried -- is to transpile the file, then run go/types on the generated Go AST. Go has excellent type-checking infrastructure; why not leverage it?

It works, sort of. You get types, but they're Go types, not GALA types. A GALA val name = "hello" becomes a Go name := std.NewImmutable[string]("hello"), and go/types tells you the type is std.Immutable[string]. Now you need a reverse-mapping layer to turn that back into string for display. A GALA Option[int] becomes std.Option[int] in Go. A sealed type variant with three fields generates a struct with a _variant uint8 discriminator. Every generated pattern needs a corresponding un-generation rule.

Worse, go/types needs complete, compilable Go code. If the user is mid-edit and the transpiler produces a partial or broken Go file, the type checker fails entirely -- no partial results, no graceful degradation. For an LSP that needs to respond to every keystroke, "all or nothing" is the wrong tradeoff.

We needed a different approach.

The solution: the transpiler already knows

Here's the insight that changed the design: the transpiler already resolves every type during transformation. When it encounters val x = Some(42), it infers that Some(42) produces Option[int], records that in its internal scope, and uses that information to generate the correct Go code. The type information exists -- it's just trapped inside the transformer's mutable state, discarded after the Go AST is emitted.

The fix was surgical. We added a parallel data structure to the transformer that records every variable's resolved type as a side effect of the normal transformation process. No separate analysis pass, no reverse mapping, no additional type checker. The transpiler does its job and the LSP reads the results.

The core of it lives in scope.go:

func (t *galaASTTransformer) addVal(name string, typeName transpiler.Type) {
    if t.currentScope != nil {
        t.currentScope.vals[name] = true
        t.currentScope.valTypes[name] = typeName
    }
    t.recordLSPVarType(name, typeName)
}

func (t *galaASTTransformer) recordLSPVarType(name string, typeName transpiler.Type) {
    if t.lspVarTypes == nil || typeName == nil || typeName.IsNil() {
        return
    }
    key := name
    if t.lspCurrentFunc != "" {
        key = t.lspCurrentFunc + "." + name
    }
    t.lspVarTypes[key] = typeName
}

Every call to addVal or addVar -- the same functions the transpiler uses to track variables for code generation -- now also records the type into lspVarTypes. The recording is conditional: if lspVarTypes is nil (normal compilation, not an LSP invocation), the function returns immediately. Zero overhead for the non-LSP path.

How types are scoped

The scoping scheme is deliberately simple. A variable inside a function is keyed as funcName.varName. A top-level variable is keyed as just varName. That's it.

The transformer tracks the current function name via lspCurrentFunc, set at the entry of each function declaration and restored on exit:

// In declarations.go, inside the function declaration handler:
prevFunc := t.lspCurrentFunc
t.lspCurrentFunc = name
defer func() { t.lspCurrentFunc = prevFunc }()

This means if you have a function calculateTotal with a local val tax = price * 0.1, the key in lspVarTypes is "calculateTotal.tax". A top-level val config = loadConfig() is just "config".

On the LSP side, lookupVarType mirrors this convention. It takes the enclosing function name (determined by scanning backwards from the cursor position for a func declaration) and tries the scoped key first, falling back to unscoped:

func lookupVarType(varTypeMap map[string]string, funcName, varName string) string {
    if varTypeMap == nil {
        return ""
    }
    if funcName != "" {
        if typStr, ok := varTypeMap[funcName+"."+varName]; ok {
            return typStr
        }
    }
    if typStr, ok := varTypeMap[varName]; ok {
        return typStr
    }
    return ""
}

This doesn't handle shadowing within nested scopes (a variable in an inner block with the same name as one in the outer function body), and that's a conscious trade-off. Full scope tracking would require mapping source positions to AST nodes, which adds complexity for a case that rarely matters in practice.

The LSP pipeline: from keystrokes to cached types

The TransformForLSP method is the bridge between the transpiler and the LSP. It calls the regular Transform, then copies out the accumulated lspVarTypes:

func (t *galaASTTransformer) TransformForLSP(richAST *transpiler.RichAST) (*transpiler.TransformResult, error) {
    fset, file, transformErr := t.Transform(richAST)
    // Always return collected var types, even on error (partial results)
    varTypes := make(map[string]transpiler.Type, len(t.lspVarTypes))
    for name, typ := range t.lspVarTypes {
        varTypes[name] = typ
    }
    return &transpiler.TransformResult{
        Fset:     fset,
        File:     file,
        VarTypes: varTypes,
    }, transformErr
}

Note the comment: "even on error (partial results)." If the transpiler fails halfway through a file -- because the user is still typing -- we still get types for every variable processed before the error. This is the critical difference from the go/types approach. Partial results are the default, not a special case.

The LSP server calls this inside analyzeFile, which runs on every document change (after a 300ms debounce). The returned VarTypes map gets cleaned up and cached:

if result != nil && result.VarTypes != nil {
    typeMap := make(map[string]string, len(result.VarTypes))
    for name, typ := range result.VarTypes {
        typeMap[name] = cleanGoTypeForDisplay(typ.String())
    }
    h.mu.Lock()
    h.varTypes[uri] = typeMap
    h.mu.Unlock()
}

The cleanGoTypeForDisplay function handles the impedance mismatch between GALA's internal type representation and what a user expects to see. It strips std. prefixes and unwraps Immutable[T] to T -- the generated Go uses Immutable wrappers to enforce value semantics on val bindings, but the user doesn't need to know that.

What this enables

With a single map[string]string per open document, the LSP gets:

Inlay hints. When the user writes val x = someExpression(), the editor shows : ReturnType as a ghost annotation after x. The inlay hint handler walks visible lines, matches val/var declarations without explicit types, and looks up the variable name in varTypes.

Dot completion. When the user types x., typeAtDot resolves x to its type via the same lookupVarType function, then looks up that type's methods and fields in the RichAST to build the completion list.

Hover information. Same lookup, different presentation -- show the type in a hover tooltip instead of a completion menu.

All three features share the exact same type resolution path. There's no separate type-checking logic for completions vs. hints vs. hover. If the transpiler resolves a type, every LSP feature sees it.

The trade-off

This design couples the LSP tightly to the transpiler's internals. If the transpiler changes how it represents types, every LSP feature is affected. But the alternative -- maintaining a separate type checker -- would mean maintaining two sources of truth that inevitably drift apart. For a language where the transpiler is the type checker, piggybacking on its results isn't coupling; it's architectural honesty.

The bigger limitation is that lspVarTypes only captures variables. Expression types (what's the type of list.Map(f).Filter(g)?) aren't in the map; those get resolved on the fly by typeAtDot walking the chain and consulting the RichAST's method signatures. That's a story for another post.

Next in the series: how dot-completion resolves method chains when the type of each step depends on the previous one.

The Problem

GALA transpiles .gala files to .go files. For single-file packages, this is fast -- parse, analyze, transform, emit. But real projects have multi-file packages. A server might have 7 files in the same package, each file needing to know about types, methods, and sealed types defined in the other 6.

Before 0.24.0, each file in a package was transpiled as a separate process invocation. The gala transpile command was called once per file, and each invocation:

1. Parsed the target file
2. Scanned all sibling files to extract type information
3. Analyzed the full dependency graph (imports, Go type inference, sealed type metadata)
4. Transformed the AST to Go
5. Emitted the output

For a 7-file package, step 2 and 3 happened 7 times, each time re-parsing the same siblings and re-resolving the same imports. The Go type inference step -- which shells out to go list to resolve return types and method signatures from Go packages -- was particularly expensive, adding hundreds of milliseconds per invocation.

The gala-server package (7 files) took 44.7 seconds. Most of that was redundant work.

Profiling First

GALA 0.24.0 introduced GALA_PROFILE=1, an environment variable that enables compilation profiling. When set, the transpiler emits timing breakdowns for every phase:

[PROFILE] Parse:     12ms
[PROFILE] Analyze:   340ms
[PROFILE] Transform: 85ms
[PROFILE] Emit:      3ms
[PROFILE] Total:     440ms

Running this across all 7 files revealed the pattern immediately: analysis dominated. Each file spent ~340ms in analysis, and the analysis for each file was doing nearly identical work -- re-parsing sibling files, re-resolving Go types, re-building sealed type metadata.

The profiling data made the optimization path obvious. Without it, we might have guessed wrong and optimized the transform phase (which was already fast) or the parser (which was negligible).

Lesson: always profile before optimizing. The GALA project enforces this as policy -- the memory file literally says "always profile with GALA_PROFILE=1 before optimizing."

Solution 1: BatchAnalyzer

The first optimization was architectural: share analysis state across files in the same package.

The BatchAnalyzer takes all files in a package at once. It parses each file, then runs a single unified analysis pass that:

• Extracts type declarations, method signatures, and sealed type definitions from all files
• Runs Go type inference once for the entire package's import set
• Builds a shared metadata cache that every file can read from

Instead of 7 analysis passes (one per file), there is now 1 analysis pass for the whole package. The analysis result is then distributed to each file's transformer.

The implementation required refactoring the analyzer's entry point. Previously, NewGalaAnalyzer accepted a single file and optional sibling file paths. The new NewBatchAnalyzer accepts all files upfront and returns a shared analysis context:

Before:  7 files x 1 analyzer each  = 7 full analyses
After:   7 files x 1 shared analyzer = 1 full analysis + 7 lookups

Solution 2: Disk Cache

Even with batch analysis, the Go type inference step (resolving return types, struct fields, and method signatures from Go standard library and third-party packages) was still expensive for the first compilation of a package.

GALA 0.24.0 introduced a disk cache at .gala/cache/. The cache stores analysis results keyed by content hash -- a SHA-256 of the file contents plus the contents of all its imports. If the file and its dependencies haven't changed, the cached analysis is reused.

The cache format is simple: JSON files named by their content hash. On a warm cache, the analysis phase drops from ~340ms to ~5ms per file, because no Go type inference or sibling parsing is needed.

Cache invalidation is content-addressed, so it is always correct: if any source file changes, its hash changes, and the cache misses. No timestamps, no file watchers, no stale cache bugs.

Solution 3: Batch Transpilation

The final piece was eliminating the process-per-file overhead. Before 0.24.0, the build system (Bazel or gala build) invoked the transpiler binary once per .gala file. Each invocation paid the cost of process startup, Go runtime initialization, and flag parsing.

Batch transpilation runs a single transpiler process for all files in a package. The process:

1. Parses all input files
2. Runs the BatchAnalyzer (one shared analysis pass)
3. Transforms each file using the shared analysis context
4. Emits all .go files

This eliminated 6 process startups (for a 7-file package) and enabled the shared analysis to happen in-memory rather than being serialized to disk and re-read.

Results

Benchmarked on the gala-server package (7 .gala files):

The warm-cache number is the steady-state experience during development: edit a file, rebuild, and the unchanged files hit the cache while only the modified file gets re-analyzed.

For single-file packages (like most examples), compilation time is unchanged at ~200-400ms. The optimization specifically targets the multi-file case where redundant work was the bottleneck.

Lessons Learned

1. Profile before optimizing. The profiling data pointed directly at analysis as the bottleneck. Without it, we might have spent time optimizing the wrong phase.

2. Shared state beats repeated computation. The batch analyzer is conceptually simple -- do the work once, share the result -- but it required restructuring the analyzer's API from "single file in, analysis out" to "all files in, shared context out."

3. Content-addressed caching is worth the investment. It is simpler than timestamp-based caching (no clock skew issues, no "did the file actually change?" ambiguity) and it is always correct. The overhead of computing SHA-256 hashes is negligible compared to the analysis it replaces.

4. Process startup costs add up. For a language tool that gets invoked hundreds of times during a build, the cost of spawning a new process each time is real. Batch mode amortizes this to one process per package.

5. The optimization was straightforward once the data was clear. There was no clever algorithm, no sophisticated caching strategy. The 22x improvement came from eliminating obviously redundant work that the profiler made visible.

Try It

GALA 0.24.0+ is available now. To see compilation timing for your own packages:

GALA_PROFILE=1 gala build ./...

The playground at https://gala-playground.fly.dev transpiles instantly (single-file), but for multi-file projects, the batch transpilation makes a meaningful difference in the edit-compile-run cycle.

The Challenge

Transpilers occupy an unusual spot in the compiler landscape. A traditional compiler owns the entire pipeline from source to machine code. A transpiler maps one language's semantics onto another language's type system, and any mismatch between the two becomes a bug.

GALA maps functional concepts -- sealed types, pattern matching, immutability, monadic types -- onto Go's type system. Go has no sum types, no pattern matching, no Option[T]. Every one of these features must be lowered into valid Go code that the Go compiler accepts. The type inference engine must reason about GALA's types (sealed variants, generic monads, lambda parameter inference) while also querying Go's type system (return types of os.ReadFile, field types of http.Request).

This two-language gap is where most of our bugs lived.

Categories of Bugs

Type Inference (35+ fixes)

Type inference bugs were the most common category. GALA's type system is richer than Go's -- it has sealed types, generic type parameter inference, lambda parameter inference from context, and Hindley-Milner-style unification for complex generic chains.

Chained method calls were a recurring source of issues. Consider:

val result = Some(42).Map((x) => x * 2).GetOrElse(0)

The transpiler must:

1. Infer that Some(42) produces Option[int]
2. Resolve Map on Option[int] with a func(int) int lambda
3. Infer the lambda parameter x as int from the method signature
4. Determine that Map returns Option[int]
5. Resolve GetOrElse on Option[int] returning int

If any step fails, the chain breaks. Early versions would lose the type at step 4, causing GetOrElse to resolve against Option[any] and generate incorrect Go code.

Void lambdas were another painful area. Go functions that take func(T) callbacks (no return value) need different treatment than func(T) U callbacks. The transpiler must detect when a lambda is expected to return nothing and avoid wrapping its body in a return statement. Getting this wrong produced Go code that failed to compile with "too many return values."

Block lambda return types required special handling. When a lambda has a block body:

val result = list.Map((x) => {
    val doubled = x * 2
    return doubled
})

The return type must be inferred from the last expression or explicit return statement inside the block. This interacts with generic type parameter substitution -- if Map is Map[U](f func(T) U) Array[U], the transpiler must unify U with the block's return type.

Code Generation (20+ fixes)

Code generation bugs produced syntactically valid but semantically wrong Go code.

Unused imports were a constant annoyance. GALA auto-imports the std package for Option, Try, etc. But if a file uses only Println (which maps to fmt.Println), the transpiler might emit an import "martianoff/gala/std" that nothing references. The Go compiler rejects unused imports, so the generated code would not compile.

The fix was an ImportManager that tracks which imports are actually referenced during code generation and only emits those. This sounds simple, but the original implementation had 4 separate import tracking subsystems that had grown organically -- one for explicit user imports, one for auto-imports, one for sealed type companions, and one for Go interop helpers. Unifying these into a single ImportManager was one of the larger refactoring efforts (covered below).

IIFE wrapping for if-expressions and match-expressions required careful handling. GALA's if and match are expressions that produce values, but Go's if and switch are statements. The transpiler wraps them in immediately-invoked function expressions:

// GALA: val x = if (cond) "yes" else "no"
// Go:
x := func() string {
    if cond {
        return "yes"
    }
    return "no"
}()

Getting the return type of these IIFEs wrong -- especially when the branches had different levels of type specificity -- caused type mismatches in the generated Go.

Cross-Package Resolution (15+ fixes)

Multi-file packages and cross-package imports introduced a class of bugs around name resolution.

Dot imports (. "package/path") bring all exported names into scope. The transpiler must know which names came from dot imports versus local definitions, because the generated Go code needs explicit package prefixes for non-dot imports. Early versions would sometimes lose track of a name's origin, generating json.Codec when the user had import . "martianoff/gala/json" (which should produce just Codec).

Sibling file scanning -- extracting type information from other files in the same package -- had to be carefully scoped. The scanner must extract type declarations, method signatures, and sealed type definitions from siblings, but it must NOT scan files from main or test packages when analyzing a library package. A bug where sibling scanning included main package files caused type corruption in library packages.

Build System (10+ fixes)

Bazel-specific bugs were their own category.

Symlinks and junctions on Windows caused issues with Bazel's sandboxing. GALA genrules need filesystem access to the Go SDK for type inference, requiring tags = ["no-sandbox"]. But Bazel still creates symlink trees for inputs, and Windows junction handling in Go's filepath.Walk behaved differently than on Linux.

Cache races in Bazel's parallel execution could cause two genrules to write the same cache file simultaneously. The fix was content-addressed caching with atomic writes (write to a temp file, then rename).

The Testing Infrastructure

Catching these bugs before users hit them required multiple layers of testing.

Compilation Gate Test

Every example in the examples/ directory (216 files as of today) has a corresponding expected-output file. The compilation gate test transpiles every example, compiles the generated Go, runs it, and compares the output. If any example fails to compile or produces wrong output, the gate fails.

This is the single most valuable test. It catches regressions that unit tests miss because unit tests test individual phases, while the gate test exercises the full pipeline end-to-end.

Type Inference Regression Suite

A dedicated test suite with 14+ cases targeting specific type inference scenarios that have broken in the past:

• Generic method chains with lambda parameter inference
• Sealed type pattern matching with nested extractors
• FoldLeft accumulator type inference from zero value
• Block lambda return type propagation through generic boundaries
• Void lambda detection for Go callback functions

Each case is a minimal .gala file that exercises one inference path. When a type inference bug is fixed, a regression case is added to prevent it from recurring.

Metadata Validation Pass

Setting GALA_VALIDATE_METADATA=1 enables a post-analysis validation pass that checks:

• All type references resolve to concrete types (no leftover NilType or any placeholders)
• All method calls resolve to known methods on the resolved type
• Sealed type variants have correct discriminator values
• Generic type parameters are fully substituted

This catches bugs where the analyzer produces metadata that looks plausible but is subtly wrong -- the kind of bug that only manifests as incorrect Go output or a confusing Go compiler error.

Battle Test Workflow

A CI workflow that builds and runs all examples, the standard library tests, and several multi-file showcase projects. It runs on both Linux and Windows to catch platform-specific issues (Windows path separators, symlink handling, GOROOT propagation).

Bug Stories

Void Lambda Error Swallowing

In version 0.22.0, we discovered that Go functions accepting func(T) callbacks could silently swallow errors. Consider:

val items = SliceOf("file1.txt", "file2.txt")
items.ForEach((name) => os.Remove(name))

os.Remove returns an error, but ForEach takes func(string) -- a void callback. The transpiler was happily compiling this, discarding the error return. In Go, ignoring an error return is at least visible in the code (_ = os.Remove(name)). In GALA, the void lambda made it invisible.

The fix had two parts. First, the transpiler now rejects void lambdas where the body expression returns an error type, producing a compile error: "void lambda discards error return from os.Remove; use Try or handle the error explicitly." Second, we added FromError(error) Try[Void] to the standard library, providing a clean way to convert Go error returns into GALA's type-safe error handling:

items.ForEach((name) => {
    FromError(os.Remove(name)).OnFailure((e) => {
        Println(s"Failed to remove $name: ${e.Error()}")
    })
})

This is a case where a bug fix led to a language feature. The Void type and FromError constructor exist because a real interop edge case demanded them.

ImportManager Unification

By version 0.22.0, the transpiler had accumulated four separate import tracking systems:

1. User imports -- explicit import declarations in the source file
2. Auto-imports -- automatically added for std, fmt, etc.
3. Sealed type imports -- added when pattern matching references companion objects from other packages
4. Go interop imports -- added when the transpiler generates calls to Go standard library functions

Each system maintained its own state, its own deduplication logic, and its own output formatting. Bugs would appear when two systems disagreed: the auto-import system would add "fmt" and then the user import system would also add "fmt", producing a duplicate import that Go rejects.

The unification in 0.23.0 replaced all four with a single ImportManager that:

• Accepts imports from any source (user, auto, sealed, interop)
• Deduplicates by import path
• Tracks actual usage during code generation
• Emits only imports that are referenced in the output

The refactoring touched 12 files and required updating every code path that previously used one of the four systems. The result was a net reduction of ~400 lines of code and elimination of an entire class of "duplicate import" and "unused import" bugs.

The 22x Performance Gain

The compilation performance story (covered in detail in the companion post) is also a reliability story. The file-at-a-time transpilation model was not just slow -- it was fragile. Each file's analysis was an independent computation, and if two files in the same package inferred slightly different metadata for a shared type (due to different analysis orderings or cache states), the generated Go files could be inconsistent.

Batch transpilation eliminated this class of bugs entirely by ensuring all files in a package see the same analysis result.

What Makes Transpiler Bugs Unique

Transpiler bugs differ from traditional compiler bugs in one important way: the error message comes from the wrong compiler.

When GALA generates incorrect Go code, the error is reported by the Go compiler -- not GALA. The user sees a Go error pointing at generated code they did not write. The mental model required to debug this ("GALA generated wrong Go, which means my GALA source triggered an edge case in the type inference engine") is harder than debugging a direct compiler error.

This is why GALA invests heavily in catching bugs before code generation. The metadata validation pass, the type inference regression suite, and the compilation gate test all exist to ensure that if something goes wrong, it fails in the GALA transpiler with a GALA-level error message, not in the Go compiler with a cryptic message about generated code.

Current State

As of version 0.25.2:

• 216 verification examples compile and produce correct output
• 14 type inference regression cases guard against known failure modes
• Full CI on Linux and Windows catches platform-specific issues
• Metadata validation available for development builds
• Zero known open bugs in the type inference engine (though new ones will certainly appear as usage grows)

The transpiler is not done. Complex generic type inference across package boundaries still has rough edges. The interaction between Go's type system and GALA's sealed types occasionally produces surprising results. But the testing infrastructure means that when bugs appear, they are caught quickly, fixed with a regression test, and stay fixed.

Try It

The GALA playground is at https://gala-playground.fly.dev. For local development:

gala build ./...
gala test ./...

If you find a bug, the best report is a minimal .gala file that fails to compile or produces wrong output. That becomes a regression test, and regression tests are how transpilers get reliable.

GALA (Go Alternative Language) is a programming language that transpiles to Go. It takes Go's runtime performance, static typing, and deployment simplicity, and adds the features that Go developers reach for repeatedly but never get: sealed types with exhaustive pattern matching, immutability by default, monadic error handling, functional collections, and type inference that actually works across generic boundaries.

GALA is not a new runtime or a managed language. Every .gala file becomes a .go file. Your existing Go libraries, tools, and deployment pipelines work unchanged. The goal is simple: write safer, more expressive code that compiles to the same fast binaries you already rely on.

Two months ago, GALA shipped version 0.0.1 -- a transpiler that could handle basic structs, val/var declarations, and simple pattern matching. Today, version 0.25.2 delivers a language with a rich standard library, a zero-reflection JSON codec, async primitives, and a compilation pipeline that processes multi-file packages in under 3 seconds.

By the Numbers

Since the first release on January 23, 2026:

• 46 releases shipped (roughly one every 1.5 days)
• 216 verification examples in the test suite
• 80+ bug fixes across type inference, code generation, and build tooling
• 19 standard library modules (std, collections, concurrent, json, regex, io, go_interop)
• 22x compilation speedup for multi-file packages (44.7s down to 2.7s)

This pace was only possible because GALA's transpilation architecture allows rapid iteration: change the transformer, run the examples, see real Go output. No bootstrapping a VM, no managing a garbage collector.

Highlight Reel

Sealed Types and Exhaustive Pattern Matching

Sealed types are GALA's answer to Go's lack of sum types. They define algebraic data types concisely, with the transpiler generating all the boilerplate -- parent structs, companion objects, Apply/Unapply methods, and discriminator checks.

sealed type Shape {
    case Circle(Radius float64)
    case Rectangle(Width float64, Height float64)
    case Point()
}

val area = shape match {
    case Circle(r)      => 3.14159 * r * r
    case Rectangle(w, h) => w * h
    case Point()         => 0.0
    // No default needed -- compiler verifies exhaustiveness
}

The standard library's Option[T], Either[A, B], and Try[T] are all sealed types. They use the same resolution mechanisms as user-defined types -- no special-casing in the transpiler.

Zero-Reflection JSON Codec

GALA's JSON codec is built on StructMeta[T], a compiler intrinsic that provides type-safe struct introspection without any reflection at runtime. The codec uses a builder pattern with naming strategies:

import . "martianoff/gala/json"

struct Person(FirstName string, LastName string, Age int)

val codec = Codec[Person](SnakeCase())
    .Omit("Password")
    .Rename("Email", "email_address")

val jsonStr = codec.Encode(person).Get()
// => {"first_name":"Alice","last_name":"Smith","age":30}

// Pattern matching on JSON strings
val result = jsonStr match {
    case codec(p) => s"Found: ${p.FirstName}, age ${p.Age}"
    case _ => "invalid JSON"
}

No struct tags. No encoding/json at runtime. The transpiler generates specialized, typed serialization code.

Functional Collections

GALA ships immutable Array, List, HashMap, TreeMap, HashSet, and TreeSet with full functional APIs:

import . "martianoff/gala/collection_immutable"

val nums = ArrayOf(1, 2, 3, 4, 5)
val doubled = nums.Map((x) => x * 2)
val sum = nums.FoldLeft(0, (acc, x) => acc + x)
val evens = nums.Filter((x) => x % 2 == 0)

// Collect: filter + transform in one pass
val evenDoubled = nums.Collect({ case n if n % 2 == 0 => n * 2 })

Sequence pattern matching works on any collection implementing the Seq interface:

val result = list match {
    case List(head, tail...) => s"First: $head, rest: ${tail.Size()}"
    case _ => "empty"
}

Monadic Error Handling: Try, Either, Future

Try[T] catches panics and wraps them as Failure, enabling railway-oriented programming without if err != nil chains:

val result = Try(() => riskyOperation())
    .Map((v) => v * 2)
    .Recover((e) => 0)

val msg = result match {
    case Success(v) => s"Got: $v"
    case Failure(e) => s"Error: ${e.Error()}"
}

Future[T] provides async computation with familiar monadic operations:

import . "martianoff/gala/concurrent"

val async = FutureApply[int](() => expensiveComputation())
val doubled = async.Map((v) => v * 2)
val value = doubled.Await().GetOrElse(0)

Default Parameters and Named Arguments

Functions support default values and named arguments -- the compiler reorders and injects them at the call site:

func connect(host string, port int = 8080, tls bool = true) Connection {
    // ...
}

connect("localhost")                // port=8080, tls=true
connect("localhost", tls = false)   // port=8080, tls=false

Named arguments also work with struct construction and Copy() method overrides.

String Interpolation

Two forms: s"..." for standard interpolation and f"..." for explicit format control:

val name = "world"
val pi = 3.14159
Println(s"Hello $name")        // Hello world
Println(f"$pi%.2f")            // 3.14

Auto-detected format verbs: %s for strings, %d for ints, %g for floats, %t for bools. No import needed for Println or Print.

22x Faster Compilation

Version 0.24.0 introduced batch transpilation, bringing multi-file package compilation from 44.7 seconds down to 2.7 seconds. The key insight: each file in a package was re-analyzing the entire dependency graph from scratch. Sharing analysis state across files in the same package eliminated the redundancy. See the companion blog post for the full story.

Retry Combinator

Version 0.25.0 added a retry combinator with pluggable backoff strategies:

import . "martianoff/gala/concurrent"

val result = Retry(
    maxRetries = 3,
    backoff = ExponentialBackoff(100),
    fn = () => fetchFromAPI(),
)

Three strategies ship out of the box: ConstantBackoff, ExponentialBackoff, and NoBackoff.

The Standard Library Today

Every standard library module follows the same rules as user code. There are no special cases in the transpiler for std types -- if you can build Option[T], you can build your own monads the same way.

Showcase Projects

Several non-trivial projects have been built with GALA during development:

• GALA Playground (https://gala-playground.fly.dev) -- a web-based editor with live transpilation, deployed on Fly.io
• gala-server -- a 7-file HTTP server package that served as the real-world benchmark for compilation performance
• State Machine -- demonstrating sealed types as state representations with exhaustive transition matching
• Log Analyzer -- a functional pipeline using Try, regex pattern matching, and collection operations

What's Next

GALA is still young. The transpiler handles a broad set of Go interop scenarios, but there are rough edges -- particularly around complex generic type inference across package boundaries. The near-term focus is:

1. Stability -- expanding the type inference regression suite beyond its current 14 cases
2. Cross-package generics -- improving type resolution for external GALA modules
3. IDE support -- GoLand plugin for GALA syntax highlighting and navigation
4. Package registry -- making it easy to publish and consume GALA libraries

If you write Go and have wished for pattern matching, immutability, or proper sum types, give GALA a try. The playground is at https://gala-playground.fly.dev, and the full language specification is in the repository.

The transpiler is honest about what it is: a source-to-source compiler that generates readable Go. When something goes wrong, you can always read the output. That transparency is a feature, not a limitation.