Add multi-version workspace and comparison tools

Author: pardeike

.github/copilot-instructions.md

@@ -1,249 +1,48 @@
 # DecompilerServer Copilot Instructions
 
-## Project Overview
+Read these files first:
+- `ARCHITECTURE.md` for durable technical rules and contracts
+- `README.md` for user-facing workflow
+- `TODO.md` for backlog
 
-This is a **DecompilerServer** project that implements an MCP (Model Context Protocol) server for decompiling and analyzing .NET assemblies, specifically focused on Unity's Assembly-CSharp.dll files. The server provides comprehensive decompilation, search, and analysis capabilities through various endpoints.
+## Repository-Specific Rules
 
-## Key Technologies & Frameworks
+- MCP tools live as static methods under `Tools/`.
+- Tools should return via `ResponseFormatter.TryExecute(...)`.
+- Discovery/search tools should route with `ToolSessionRouter.GetForContext(...)`.
+- `memberId` follow-up tools should route with `ToolSessionRouter.GetForMember(...)`.
+- Reuse `TypeSurfaceComparer` for type-surface semantics instead of duplicating compare logic.
+- Use `DecompilerService.DecompileEntitySnippet(...)` for focused compare body retrieval.
+- Prefer structured JSON output over pre-rendered diff text for overview commands.
 
-- **.NET 8.0** - Target framework
-- **ICSharpCode.Decompiler** - Core decompilation engine
-- **Microsoft.Extensions.Hosting** - Hosting and dependency injection
-- **ModelContextProtocol** - MCP server implementation
-- **System.Text.Json** - JSON serialization with camelCase naming
-- **xUnit** - Testing framework
+## Workspace and Compare Expectations
 
-## Project Structure
+- Assume multi-context workspace support is the primary model.
+- Preserve stable member ID format: `<mvid-32hex>:<token-8hex>:<kind-code>`.
+- `compare_contexts` is structural. `changed` means direct member surface changed.
+- `compare_symbols(compareMode: "body")` is method-only and should stay opt-in.
+- Do not broaden compare semantics casually; update `ARCHITECTURE.md` if a durable contract changes.
 
-```
-DecompilerServer/
-├── Services/                      # Core service implementations
-│   ├── AssemblyContextManager.cs  # Assembly loading and context management
-│   ├── DecompilerService.cs       # C# decompilation with caching
-│   ├── MemberResolver.cs          # Member ID resolution and normalization
-│   ├── SearchServiceBase.cs       # Base search and pagination functionality
-│   ├── UsageAnalyzer.cs           # Code usage analysis
-│   ├── InheritanceAnalyzer.cs     # Inheritance relationship analysis
-│   └── ResponseFormatter.cs       # JSON response formatting
-├── Tools/                         # MCP tool implementations (static methods)
-│   ├── ResolveMemberId.cs         # Member ID validation
-│   ├── ListNamespaces.cs          # Namespace enumeration
-│   ├── SearchTypes.cs             # Type discovery with search
-│   ├── GetDecompiledSource.cs     # Core decompilation to C#
-│   ├── GetSourceSlice.cs          # Source code range viewing
-│   └── GetMemberDetails.cs        # Rich member metadata
-├── Tests/                         # xUnit test suite
-├── TestLibrary/                   # Test assembly for validation
-├── ServiceLocator.cs              # Service locator for MCP tools
-├── Program.cs                     # Application entry point
-└── *.md                           # Documentation files
-```
-
-## Documentation
-
-### Developer Guides
-- **[HELPER_METHODS_GUIDE.md](../HELPER_METHODS_GUIDE.md)** - Comprehensive guide to all service helper methods and implementation patterns for MCP tools. Essential reading for understanding the service architecture and implementing new endpoints.
-- **[TESTING.md](../TESTING.md)** - Complete testing framework documentation covering xUnit setup, test data structure, and testing patterns. Required reading for writing tests and understanding the test infrastructure.
-- **[TODO.md](../TODO.md)** - Comprehensive list of prioritized TODOs and enhancement opportunities based on thorough code review. Organized by priority and complexity for systematic AI-assisted development. Contains detailed context and reasoning for each improvement.
-
-All guides are actively maintained and provide crucial implementation guidance for developers working on the DecompilerServer.
-
-## Core Architecture Principles
-
-### Member ID System
-- **Format**: `<mvid-32hex>:<token-8hex>:<kind-code>`
-- **Kind Codes**: T=Type, M=Method/Constructor, P=Property, F=Field, E=Event, N=Namespace
-- All member IDs must be stable and consistent across sessions
-
-### Threading & Performance
-- Use `ReaderWriterLockSlim` for thread-safe access (fast reads, guarded writes)
-- Implement lazy indexing - build minimal maps on first access
-- Cache decompiled source with line indexing for efficient slicing
-- Always paginate results (default limit: 50, max: 500)
-
-### Error Handling
-- Return structured errors: `{ error: { code, message, detail? } }`
-- Never throw exceptions across MCP boundaries
-- Handle assembly loading failures gracefully
-
-## Code Style & Conventions
-
-### Formatting
-- **Important**: Run `dotnet format DecompilerServer.sln` before committing
-- During development, focus on functionality over formatting
-- The formatter will handle code style consistency
+## Testing
 
-### Naming Conventions
-- Use PascalCase for public members and types
-- Use camelCase for private fields and local variables
-- Prefix private fields with underscore (`_fieldName`)
-- Use descriptive names for member IDs and handles
+- Use xUnit and real compiled test assemblies.
+- `Tests/ServiceTestBase.cs` is the base fixture for service-level tests.
+- Add dedicated `*ToolTests.cs` files for MCP tool behavior.
+- Use `Tests/TemporaryAssemblyBuilder.cs` for controlled version-drift and compare tests.
+- When tests need workspace-aware behavior, register `DecompilerWorkspace` in the test service provider.
 
-### JSON Serialization
-- Use camelCase property naming
-- Ignore null values in output
-- Ensure deterministic ordering for stable diffs
+## Verification
 
-## Development Workflow
+Run after code changes:
 
-### Building & Testing
 ```bash
-# Build the solution
-dotnet build DecompilerServer.sln
-
-# Run tests
-dotnet test DecompilerServer.sln
-
-# Format code before committing
 dotnet format DecompilerServer.sln
+dotnet test -c Release --no-restore
 ```
 
-### Test Strategy
-- All service helpers have comprehensive tests using real test assembly
-- Use `ServiceTestBase` for integration tests with loaded test.dll
-- Validate both functionality and output format
-- Test with various C# constructs (generics, inheritance, attributes, etc.)
-
-## Key Implementation Guidelines
-
-### Assembly Context Management
-- Maintain single in-memory context with PEFile, UniversalAssemblyResolver, DecompilerTypeSystem
-- Load assemblies with `PEStreamOptions.PrefetchEntireImage` (or equivalent in-memory loading) so the source DLL is not kept locked on disk
-- Configure resolver with appropriate search directories (Game*_Data/Managed, Unity directories)
-- Use proper decompiler settings (UsingDeclarations, ShowXmlDocumentation, NamedArguments)
-- `Unload` should clear the current assembly context and caches without disposing the singleton `AssemblyContextManager`; reserve `Dispose()` for service/provider shutdown
-
-### Search & Pagination
-- Implement cursor-based pagination for all search endpoints
-- Support filtering by accessibility, member types, namespaces
-- Return structured results with `{ items, nextCursor, totalEstimate }`
-
-### Source Management
-- Cache decompiled C# source with line indexing
-- Support ranged retrieval without re-decompilation
-- Include proper headers/footers and maintain source document metadata
-- When decompiling nested types by name, prefer reflection names such as `Outer+Inner`; dotted names such as `Outer.Inner` can fail in ILSpy lookup paths even when the type exists in metadata.
-
-### IL Handling
-- Use ICSharpCode.Decompiler.Disassembler for readable IL output
-- Leverage MetadataReader, avoid reflection-only loading
-- Provide both IL and decompiled C# views
-
-## Common Patterns
-
-**See [HELPER_METHODS_GUIDE.md](../HELPER_METHODS_GUIDE.md) for comprehensive service helper documentation and implementation patterns.**
-
-### Service Dependencies
-Services typically depend on:
-- `AssemblyContextManager` - for assembly access
-- `MemberResolver` - for ID resolution and validation
-- Other services as needed for specific functionality
-
-### MCP Tool Dependencies
-MCP tools (static methods) access services via:
-- `ServiceLocator.ContextManager` - assembly context access
-- `ServiceLocator.MemberResolver` - member ID operations
-- `ServiceLocator.DecompilerService` - source decompilation
-- `ServiceLocator.ResponseFormatter` - consistent JSON responses
-
-### Response Models
-Use consistent model types (defined in shared Models.cs):
-- `MemberHandle`, `MemberSummary`, `SearchResult<T>`
-- `MemberDetails`, `SourceDocument`, `SourceSlice`
-- `UsageRef`, `GraphResult`, `Stats`
-
-### Error Responses
-Always return structured error objects rather than throwing exceptions when implementing MCP endpoints.
-
-## Testing Considerations
-
-- Use the TestLibrary project for consistent test data
-- Test with various C# language features and constructs
-- Validate both service functionality and JSON output format
-- Ensure thread safety in concurrent scenarios
-- Test pagination and cursor handling
-
-**See [TESTING.md](../TESTING.md) for complete testing framework documentation and best practices.**
-
-### MCP Tool Testing Patterns
-When implementing MCP tools (static methods), follow these patterns:
-
-- **ServiceLocator Setup**: Create a service provider in test constructor and register all required services:
-  ```csharp
-  public ToolImplementationTests()
-  {
-      var services = new ServiceCollection();
-      services.AddSingleton(ContextManager);
-      services.AddSingleton(MemberResolver);
-      services.AddSingleton<DecompilerService>();
-      services.AddSingleton<UsageAnalyzer>();
-      services.AddSingleton<InheritanceAnalyzer>();
-      services.AddSingleton<ResponseFormatter>();
-
-      _serviceProvider = services.BuildServiceProvider();
-      ServiceLocator.SetServiceProvider(_serviceProvider);
-  }
-  ```
-
-- **Service Dependencies**: Always register services in the correct dependency order:
-  1. `AssemblyContextManager` (core, no dependencies)
-  2. `MemberResolver` (depends on AssemblyContextManager)
-  3. All other services (DecompilerService, UsageAnalyzer, etc.)
-  4. `ResponseFormatter` (standalone)
-
-- **Test Cleanup**: Do NOT override Dispose() with [Fact] attribute - this causes xUnit errors. Let ServiceTestBase handle disposal naturally.
-
-- **SearchService Pattern**: When tools need SearchServiceBase functionality, create a concrete implementation:
-  ```csharp
-  internal class SearchService : SearchServiceBase
-  {
-      public SearchService(AssemblyContextManager contextManager, MemberResolver memberResolver)
-          : base(contextManager, memberResolver) { }
-  }
-  ```
-
-## Performance Optimization
-
-- Implement lazy loading for expensive operations
-- Use concurrent collections for thread-safe caching
-- Build indexes incrementally rather than upfront
-- Consider memory usage when caching large decompiled sources
-
-## MCP Tool Implementation Guidelines
-
-### Static Method Pattern
-MCP tools must be implemented as static methods with specific attributes:
-```csharp
-[McpServerTool, Description("Tool description")]
-public static string ToolName(parameters...)
-{
-    return ResponseFormatter.TryExecute(() =>
-    {
-        // Access services via ServiceLocator
-        var service = ServiceLocator.GetRequiredService<ServiceType>();
-        // Implementation logic
-        return result;
-    });
-}
-```
-
-### ServiceLocator Usage
-- Use ServiceLocator pattern to provide dependency injection for static MCP tools
-- Always check if assembly is loaded before performing operations
-- Use ResponseFormatter.TryExecute() for consistent error handling across all tools
-
-## Final Development Step
-
-**Before completing any major work or making the final commit, always review and update `.github/copilot-instructions.md` if:**
-- You encountered unexpected patterns or pitfalls during development
-- New architectural patterns or testing approaches were discovered
-- Additional framework-specific guidance would help future development
-- The current instructions have become outdated or incomplete
-
-**When working on improvements, refer to [TODO.md](../TODO.md) for:**
-- Prioritized list of enhancement opportunities  
-- Detailed context and reasoning for each improvement
-- Implementation guidelines and testing requirements
-- Technical debt items and maintenance tasks
+## Documentation Policy
 
-This ensures knowledge from each development cycle is captured for improved efficiency in future work, and provides a systematic approach to project enhancement.
+- Keep durable technical content in `ARCHITECTURE.md`.
+- Keep `README.md` user-facing.
+- Keep `TODO.md` backlog-focused.
+- Do not add new helper, testing, or plan documents unless there is a durable need that cannot fit those files.

AGENTS.md

@@ -1 +1,5 @@
-Use .github/copilot-instructions.md  for more information. It contains everything this file should have
+Read `.github/copilot-instructions.md` for repository-specific working rules.
+
+Read `ARCHITECTURE.md` for the durable technical reference and `TODO.md` for backlog.
+
+Do not reintroduce deleted helper, testing, plan, or implementor docs unless the information is durable and cannot live in `README.md`, `ARCHITECTURE.md`, or `TODO.md`.