AGENTS.md

1# Compiler Architecture
2 
3## Intro
4 
5Consider reading [fir-basics.md](../docs/fir/fir-basics.md).
6 
7## Two Frontends
8 
91. **K1/FE 1.0 (Legacy)**: Located in `compiler/frontend/` - uses PSI and BindingContext
102. **K2/FIR (Current)**: Located in `compiler/fir/` - Frontend IR, the new compiler frontend
11 
12## FIR Compilation Phases
13 
14FIR processes code through sequential phases (see `FirResolvePhase.kt`).
15 
16Key invariant: In phase B following phase A, all FIR elements visible in B are resolved to phase A.
17 
18## IR (Intermediate Representation)
19 
20Located in `compiler/ir/`. Backend IR is used by all targets for:
21- Lowering (transforming code to target-friendly form)
22- Optimization
23- Serialization to klibs
24 
25Backend implementations:
26- `compiler/ir/backend.jvm/` - JVM backend
27- `compiler/ir/backend.js/` - JavaScript backend
28- `compiler/ir/backend.wasm/` - WebAssembly backend
29- `kotlin-native/backend.native/`, `native/` - Native backend
30 
31## Inference
32 
33For type inference implementation details, read [inference.md](../docs/fir/inference.md).
34 
35## Commit Guidelines
36 
37- **FIR prefix**: When changes are mostly related to FIR (`compiler/fir/`), use `FIR: ` prefix in the commit subject line.
38- **Test-before-fix**: When fixing an issue and adding a test, commit the test data as a separate commit **before** the fix. This helps reviewers see how the fix actually changes semantics (the test will show diagnostic differences in the fix commit).
39 
40## Testing
41 
42For FIR analysis test data format (directives, diagnostic markers, file structure), see [analysis-tests/AGENTS.md](fir/analysis-tests/AGENTS.md).