Copilot instructions

1---
2applyTo: "src/{Compilers,Dependencies,ExpressionEvaluator,Tools}/**/*.{cs,vb}"
3---
4 
5# Roslyn Compiler Instructions for AI Coding Agents
6 
7## Architecture Overview
8 
9Roslyn follows a **layered compiler architecture**:
10- **Lexer → Parser → Syntax Trees → Semantic Analysis → Lowering/Rewriting → Symbol Tables → Emit**
11- Core abstraction: `Compilation` is immutable and reusable. Create new compilations via `AddSyntaxTrees()`, `RemoveSyntaxTrees()`, `ReplaceSyntaxTree()` for incremental changes
12- **Internal vs Public APIs**: Use `InternalSyntax` namespace for performance-critical parsing; `Microsoft.CodeAnalysis` for public consumption
13 
14### Key Directories
15- `src/Compilers/Core/Portable/` - Language-agnostic compiler infrastructure
16- `src/Compilers/CSharp/Portable/` - C# compiler implementation  
17- `src/Compilers/VisualBasic/Portable/` - VB compiler implementation
18- `src/Compilers/Server/` - `VBCSCompiler` build server
19- `src/Dependencies/` - High-performance collections (`PooledObjects`, `Threading`)
20- `src/ExpressionEvaluator/` - Debugger expression evaluation (uses special `LexerMode.DebuggerSyntax`)
21- `src/Tools/` - Compiler tooling (BuildBoss, format tools, analyzers)
22 
23### Essential Files for Context
24- `src/Compilers/CSharp/Portable/Errors/ErrorCode.cs` - All C# compiler error codes
25- `src/Compilers/CSharp/Portable/Errors/MessageID.cs` - Language feature version gating
26- `src/Compilers/CSharp/Portable/Syntax/Syntax.xml` - Syntax tree node definitions (generated code source)
27- `src/Compilers/CSharp/Portable/BoundTree/BoundNodes.xml` - Bound tree node definitions (generated code source)
28- `docs/wiki/Roslyn-Overview.md` - Architecture deep-dive
29 
30## Code Generation
31 
32Several core data structures are generated from XML definitions — **never edit the generated `.cs` or `.vb` files directly**:
33- **Syntax trees**: `src/Compilers/CSharp/Portable/Syntax/Syntax.xml`
34- **Bound trees**: `src/Compilers/CSharp/Portable/BoundTree/BoundNodes.xml`
35- After modifying these XML files, regenerate and build:
36```bash
37  dotnet run --file eng/generate-compiler-code.cs
38  dotnet build src/Compilers/{CSharp,VisualBasic}/Portable # choose the project matching the C# or VB syntax you changed
39```
40 
41## Conventions
42 
43- **MEF is not used in the compiler layer.** `ExportLanguageService` / `ImportingConstructor` and the IDE service model are IDE-layer concepts — ignore them here.
44- **Null checks**: validate internal-API preconditions with `Debug.Assert(...)` (a violated internal precondition may NRE in release); validate public APIs with explicit null checking when appropriate, throwing a dedicated exception with a localized string.
45- **Immutability** is via `Compilation` (`AddSyntaxTrees`/`RemoveSyntaxTrees`/`ReplaceSyntaxTree`), not the workspace `Document`/`Solution` model.
46 
47## Essential Patterns
48 
49### Memory Management
50- **Avoid LINQ in hot paths** - use manual enumeration or `struct` enumerators
51- **Avoid `foreach` over collections without struct enumerators** 
52- **Use object pools extensively** - see patterns in `src/Dependencies/PooledObjects/`
53- **Prefer `Debug.Assert()` over exceptions** for internal validation
54 
55## Build & Test Workflows
56 
57### Essential Build Commands
58 
59```powershell
60# Full build (use VS Code tasks when available)
61./build.sh
62 
63# Build specific components  
64dotnet build Compilers.slnf                    # Compiler-only build
65dotnet build src/Compilers/CSharp/csc/AnyCpu/  # C# compiler
66 
67# Generate compiler code after changes
68dotnet run --file eng/generate-compiler-code.cs
69```
70 
71## Debugger Integration
72 
73**Expression Evaluator** uses special parsing modes:
74- `LexerMode.DebuggerSyntax` for expression evaluation
75- `IsInFieldKeywordContext` flag for context-aware parsing
76- `ConsumeFullText` parameter for complete expression parsing
77 
78## MSBuild Integration
79 
80Compiler tasks are in `src/Compilers/Core/MSBuildTask/`:
81- `Csc.cs` - C# compiler task
82- `Vbc.cs` - VB compiler task  
83- `ManagedCompiler.cs` - Base compiler task functionality
84 
85## Performance Considerations
86 
871. **Lexer/Parser optimizations**: Use `InternalSyntax` types for performance-critical code
882. **Immutable data structures**: Roslyn heavily uses immutable collections and copy-on-write semantics
893. **Caching**: `Compilation` objects cache semantic information - reuse when possible
904. **Threading**: Most compiler operations are thread-safe through immutability
91 
92## Symbol Resolution
93 
94Navigate the symbol hierarchy:
95```cs
96var compilation = CreateCompilation(source);
97var globalNamespace = compilation.GlobalNamespace;
98var typeSymbol = globalNamespace.GetTypeMembers("MyClass").Single();
99var methodSymbol = typeSymbol.GetMembers("MyMethod").Single();
100```
101 
102Symbol equality is complex due to generics and substitution - always test with multiple generic scenarios.
103