randlee · randlee · Jan 15, 2026 · Jan 15, 2026 · Jan 15, 2026 · Jan 15, 2026
diff --git a/.serena/memories/code_style.md b/.serena/memories/code_style.md
@@ -0,0 +1,27 @@
+# Code Style and Conventions
+
+## Namespace Style
+- File-scoped namespaces (no braces): `namespace RoslynDiff.Output;`
+
+## Documentation
+- XML documentation comments for public APIs
+- Use `/// <inheritdoc/>` for interface implementations
+- Summary sections for classes and methods
+
+## Code Patterns
+- Records for immutable data models
+- Collection expressions `[]` for initializing collections
+- Pattern matching with `is` and `switch` expressions
+- Async/await with Task-based async pattern
+
+## Testing Style
+- xUnit with `[Fact]` attributes
+- FluentAssertions for assertions
+- Arrange/Act/Assert pattern in comments
+- Test class naming: `{ClassName}Tests`
+- Test method naming: `{MethodName}_{Condition}_{ExpectedResult}`
+
+## Null Handling
+- Nullable reference types enabled
+- Use `??=` for null-coalescing assignment
+- Use `?.` for null-conditional access
diff --git a/.serena/memories/project_overview.md b/.serena/memories/project_overview.md
@@ -0,0 +1,38 @@
+# roslyn-diff Project Overview
+
+## Purpose
+roslyn-diff is a semantic diff tool for .NET using Roslyn. It provides semantic-aware diffing capabilities for C# code, understanding code structure rather than just line-by-line text comparison.
+
+## Tech Stack
+- .NET 10.0
+- C#
+- Roslyn (Microsoft.CodeAnalysis) for semantic code analysis
+- Spectre.Console for rich terminal output
+- xUnit for testing with FluentAssertions and NSubstitute
+
+## Project Structure
+- `src/RoslynDiff.Core/` - Core diff engine and models
+- `src/RoslynDiff.Output/` - Output formatters (JSON, HTML, Plain Text, Terminal/Spectre)
+- `src/RoslynDiff.Cli/` - Command-line interface
+- `tests/` - Unit tests for each project
+
+## Key Models (in RoslynDiff.Core.Models)
+- `DiffResult` - Main result containing file changes and stats
+- `Change` - Individual change with type, kind, location, content
+- `ChangeType` - Added, Removed, Modified, Moved, Renamed, Unchanged
+- `ChangeKind` - File, Namespace, Class, Method, Property, Field, Statement, Line
+- `DiffStats` - Statistics about changes
+
+## Output Formatters
+Implement `IOutputFormatter` interface with:
+- `Format` property (format identifier like "json", "text", "terminal")
+- `ContentType` property (MIME type)
+- `FormatResult()` method
+- `FormatResultAsync()` method
+
+Available formatters:
+- JsonOutputFormatter - JSON output
+- PlainTextFormatter - Simple text (no ANSI codes, good for pipes)
+- SpectreConsoleFormatter - Rich terminal output with colors
+- HtmlFormatter - HTML output
+- UnifiedFormatter - Unified diff format
diff --git a/.serena/memories/suggested_commands.md b/.serena/memories/suggested_commands.md
@@ -0,0 +1,30 @@
+# Suggested Commands for roslyn-diff
+
+## Building
+```bash
+dotnet build              # Build the entire solution
+dotnet build src/RoslynDiff.Output/RoslynDiff.Output.csproj  # Build specific project
+```
+
+## Testing
+```bash
+dotnet test               # Run all tests
+dotnet test --no-build    # Run tests without rebuilding
+dotnet test --filter "FullyQualifiedName~PlainTextFormatterTests"  # Run specific tests
+```
+
+## Cleaning
+```bash
+dotnet clean              # Clean build artifacts
+```
+
+## Running the CLI
+```bash
+dotnet run --project src/RoslynDiff.Cli -- <args>
+```
+
+## Git
+```bash
+git status                # Check modified files
+git diff                  # See changes
+```
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,7 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Git integration (compare commits, branches)
 - F# support via FSharp.Compiler.Service
 
-## [1.0.0] - 2025-XX-XX
+## [0.5.0] - 2026-01-15
 
 ### Added
 
@@ -93,7 +93,7 @@ This project follows [Semantic Versioning](https://semver.org/):
 
 | Phase | Version | Features |
 |-------|---------|----------|
-| Phase 1 | v1.0.0 | Core CLI (current) |
+| Phase 1 | v0.5.0 | Core CLI (current) |
 | Phase 2 | v1.x | MCP Server integration |
 | Phase 3 | v2.0 | Folder/project/git support |
 | Phase 4 | v3.0 | Solution-level comparison |

diff --git a/Directory.Build.props b/Directory.Build.props
@@ -13,10 +13,17 @@
     <NoWarn>$(NoWarn);1591</NoWarn>
   </PropertyGroup>
 
+  <!-- Version: Single source of truth for all assemblies and NuGet packages -->
+  <PropertyGroup>
+    <Version>0.5.0</Version>
+    <AssemblyVersion>0.5.0.0</AssemblyVersion>
+    <FileVersion>0.5.0.0</FileVersion>
+  </PropertyGroup>
+
   <PropertyGroup>
     <Authors>RoslynDiff Contributors</Authors>
     <Company>RoslynDiff</Company>
-    <Copyright>Copyright (c) 2025 RoslynDiff Contributors</Copyright>
+    <Copyright>Copyright (c) 2025-2026 RoslynDiff Contributors</Copyright>
     <RepositoryUrl>https://github.com/randlee/roslyn-diff</RepositoryUrl>
     <RepositoryType>git</RepositoryType>
   </PropertyGroup>

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -0,0 +1,183 @@
+# roslyn-diff v0.5.0 Release Notes
+
+**Release Date:** January 15, 2026
+
+## Release Highlights
+
+This is the first stable release of roslyn-diff, a semantic diff tool for .NET source code using the Roslyn compiler platform. Unlike traditional line-by-line diff tools, roslyn-diff understands code structure, enabling it to detect and report changes at the semantic level.
+
+### Key Capabilities
+
+- **Semantic Code Understanding** - Uses Roslyn to parse and analyze code structure
+- **Multi-Language Support** - Full semantic diff for C# and VB.NET; line-based diff for other files
+- **Intelligent Change Detection** - Detects additions, deletions, modifications, renames, and moves
+- **Flexible Output** - JSON for AI/tooling, HTML reports, and terminal output
+- **Class Comparison** - Compare specific classes with multiple matching strategies
+
+## Features
+
+### Semantic Diff Engine
+
+- **C# Support** - Full semantic analysis of C# source files (.cs)
+- **VB.NET Support** - Full semantic analysis of Visual Basic source files (.vb)
+- **Line-by-Line Fallback** - Traditional diff for non-.NET files using DiffPlex
+- **Rename Detection** - Identifies when symbols are renamed rather than added/removed
+- **Move Detection** - Detects code that has been relocated within a file
+
+### Change Detection
+
+Detects changes to:
+- Classes, structs, records, and interfaces
+- Methods and functions
+- Properties and fields
+- Namespaces
+- Statement-level changes (in Roslyn mode)
+
+### CLI Commands
+
+#### `diff` Command
+Compare two files with semantic understanding:
+```bash
+roslyn-diff diff old.cs new.cs
+roslyn-diff diff old.cs new.cs --output json
+roslyn-diff diff old.cs new.cs --output html --out-file report.html
+```
+
+**Options:**
+- `--mode <auto|roslyn|line>` - Select diff algorithm
+- `--ignore-whitespace` / `-w` - Ignore whitespace differences
+- `--ignore-comments` / `-c` - Ignore comment differences
+- `--context` / `-C` - Control context lines
+- `--output` / `-o` - Select output format (json, html, text, plain, terminal)
+- `--rich` / `-r` - Rich terminal output with colors
+
+#### `class` Command
+Compare specific classes between files:
+```bash
+roslyn-diff class old.cs:Calculator new.cs:Calculator
+roslyn-diff class old.cs new.cs --match-by interface --interface IRepository
+```
+
+**Options:**
+- `--match-by <exact|interface|similarity|auto>` - Matching strategy
+- `--interface` / `-i` - Interface name for interface matching
+- `--similarity` / `-s` - Similarity threshold (0.0-1.0)
+
+### Output Formats
+
+| Format | Description | Best For |
+|--------|-------------|----------|
+| `json` | Machine-readable structured output | AI tools, CI/CD, automation |
+| `html` | Interactive report with syntax highlighting | Code reviews, documentation |
+| `text` | Unified diff format (like git diff) | Quick review, command line |
+| `plain` | Simple text without ANSI codes | Piping, scripting |
+| `terminal` | Rich console output with colors | Interactive terminal use |
+
+### Programmatic API
+
+Use roslyn-diff as a library in your .NET applications:
+
+```csharp
+using RoslynDiff.Core.Differ;
+using RoslynDiff.Core.Models;
+
+var factory = new DifferFactory();
+var differ = factory.GetDiffer("file.cs", new DiffOptions());
+var result = differ.Compare(oldContent, newContent, options);
+```
+
+## Installation
+
+### As a .NET Tool (Recommended)
+
+```bash
+dotnet tool install -g roslyn-diff
+```
+
+### From Source
+
+```bash
+git clone https://github.com/randlee/roslyn-diff.git
+cd roslyn-diff
+dotnet build
+```
+
+### Run Without Installing
+
+```bash
+cd src/RoslynDiff.Cli
+dotnet run -- diff old.cs new.cs
+```
+
+## Requirements
+
+- .NET 10.0 or later
+
+## Dependencies
+
+- Microsoft.CodeAnalysis.CSharp 4.12.0
+- Microsoft.CodeAnalysis.VisualBasic 4.12.0
+- DiffPlex 1.7.2
+- Spectre.Console 0.49.x
+- System.CommandLine 2.0.0-beta4
+
+## Breaking Changes
+
+None - this is the initial stable release.
+
+## Known Issues
+
+- Large files (1000+ methods) may experience longer processing times (3-10 seconds)
+- Roslyn mode requires .cs or .vb files; other extensions fall back to line diff
+- System.CommandLine is in beta; some edge cases in argument parsing may exist
+
+## Migration from Pre-release Versions
+
+If upgrading from 0.x pre-release versions:
+
+1. **CLI Changes**
+   - `--format` has been renamed to `--output` / `-o`
+   - Default output format is now `text` (was `terminal`)
+   - Use `--rich` / `-r` for colored terminal output
+
+2. **API Changes**
+   - `DiffResult` is now a record type (immutable)
+   - `Change.Location` split into `OldLocation` and `NewLocation`
+   - `OutputFormatter` interface renamed to `IOutputFormatter`
+
+3. **JSON Output Schema**
+   - Schema version updated to `roslyn-diff-output-v1`
+   - `summary` object structure changed
+   - Location objects now include `startColumn` and `endColumn`
+
+## Documentation
+
+- [README](./README.md) - Getting started guide
+- [Usage Guide](./docs/usage.md) - Detailed CLI usage
+- [Output Formats](./docs/output-formats.md) - Format specifications
+- [API Reference](./docs/api.md) - Programmatic API documentation
+- [Architecture](./docs/architecture.md) - Project design
+- [Performance Guide](./docs/performance.md) - Benchmarks and optimization
+
+## Future Roadmap
+
+Planned for future releases:
+- MCP Server integration for AI tooling (v1.x)
+- Folder/project comparison (v2.0)
+- Git integration (compare commits, branches) (v2.0)
+- F# support via FSharp.Compiler.Service (v2.0)
+- Solution-level comparison (v3.0)
+
+## Acknowledgments
+
+- [Roslyn](https://github.com/dotnet/roslyn) - The .NET Compiler Platform
+- [DiffPlex](https://github.com/mmanela/diffplex) - .NET Diff library
+- [Spectre.Console](https://github.com/spectreconsole/spectre.console) - Beautiful console applications
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) for details.
+
+---
+
+Full changelog available at [CHANGELOG.md](./CHANGELOG.md)
diff --git a/docs/output-formats.md b/docs/output-formats.md
@@ -42,7 +42,7 @@ roslyn-diff diff old.cs new.cs -o json --out-file diff.json
   "$schema": "roslyn-diff-output-v1",
   "metadata": {
     "tool": "roslyn-diff",
-    "version": "1.0.0",
+    "version": "0.5.0",
     "timestamp": "2025-01-14T20:00:00Z",
     "mode": "roslyn",
     "oldPath": "old/Service.cs",

diff --git a/icon.png b/icon.png
diff --git a/icon.svg b/icon.svg
diff --git a/plan/sprint-plan.md b/plan/sprint-plan.md
@@ -1,5 +1,26 @@
 # roslyn-diff - Sprint Plan
 
+## Progress Summary (Updated: 2026-01-15)
+
+| Sprint | Status | Tests | Key Deliverables |
+|--------|--------|-------|------------------|
+| Sprint 1 | ✅ Complete | 52 | LineDiffer, DifferFactory, Basic CLI |
+| Sprint 2 | ✅ Complete | 65 | CSharpDiffer, SyntaxComparer, NodeMatcher |
+| Sprint 3 | ✅ Complete | 242 | VisualBasicDiffer, SemanticComparer, SymbolMatcher |
+| Sprint 4 | ✅ Complete | 242 | JsonFormatter, HtmlFormatter, PlainText, SpectreConsole |
+| Sprint 5 | ✅ Complete | 361 | ClassMatcher, `class` command, CLI options |
+| Sprint 6 | ✅ Complete | 650 | Edge case tests, Integration tests, Documentation, Benchmarks |
+| Sprint 7 | ✅ Complete | 650 | NuGet package config, Release artifacts, Final testing |
+
+### Current State
+- **Branch**: release/v0.5.0
+- **Open PR**: #4 (release/v0.5.0 → main) - Contains Sprint 7
+- **Total Tests**: 650 passing (321 Core + 130 Output + 84 CLI + 115 Integration)
+- **Documentation**: Complete (README, docs/, samples/, CHANGELOG, RELEASE_NOTES)
+- **Package**: Configured and tested (ready for NuGet publish)
+
+---
+
 ## Sprint Overview
 
 | Sprint | Focus | Duration | Dependencies |

diff --git a/samples/output-example.html b/samples/output-example.html
@@ -323,7 +323,7 @@ <h2>Changes</h2>
         </div>
 
         <footer>
-            Generated by roslyn-diff v1.0.0<br>
+            Generated by roslyn-diff v0.5.0<br>
             Mode: Roslyn (semantic diff)
         </footer>
     </div>