NUnit Migration: `dotnet format` crashes on multi-targeted projects

[thomhurst]

Description

When running the TUnit NUnit migration code fixer on projects that target multiple frameworks (e.g., <TargetFrameworks>net8.0;net9.0;net10.0;net462</TargetFrameworks>), the dotnet format analyzers command crashes with an exception related to linked file merging.

Steps to Reproduce

1. Create a project with NUnit tests that targets multiple frameworks:

   <TargetFrameworks>net8.0;net9.0;net10.0;net462</TargetFrameworks>

2. Add TUnit packages
3. Run dotnet format analyzers --severity info --diagnostics TUNU0001

Expected Behavior

The migration should complete successfully for all target frameworks.

Actual Behavior

The command crashes with the following error:

Unhandled exception: System.AggregateException: One or more errors occurred. 
(Changes must be within bounds of SourceText (Parameter 'changes'))
 ---> System.ArgumentException: Changes must be within bounds of SourceText (Parameter 'changes')
   at Microsoft.CodeAnalysis.Text.SourceText.WithChanges(IEnumerable`1 changes)
   at Microsoft.CodeAnalysis.LinkedFileMergeConflictCommentAdditionService.GetCommentChangesForDocument(...)
   at Microsoft.CodeAnalysis.LinkedFileDiffMergingSession.MergeLinkedDocumentGroupAsync(...)
   ...

The migration process appears to identify files to format and attempts changes, but crashes when trying to merge the changes across multiple target frameworks.

Workaround

Temporarily change the project to a single target framework:

<TargetFramework>net8.0</TargetFramework>
<!-- <TargetFrameworks>net8.0;net9.0;net10.0;net462</TargetFrameworks> -->

Then run the migration, and restore multi-targeting afterward.

Notes

This may be a dotnet format issue rather than a TUnit code fixer issue, but it significantly impacts the migration experience for projects with multiple target frameworks.

The error occurs in Microsoft.CodeAnalysis.LinkedFileMergeConflictCommentAdditionService, suggesting the issue is with how changes are being merged across the same files compiled for different target frameworks.

Possible Solutions

1. Document the workaround in migration guide
2. Investigate if the TUnit code fixer can make changes more compatible with linked file scenarios
3. Report to dotnet/format if this is an upstream issue

Environment

• TUnit version: 1.9.91
• .NET version: .NET 8.0 (dotnet format from .NET 10.0.101 SDK)
• OS: Windows
• dotnet format version: (from .NET SDK 10.0.101)

[thomhurst]

Root Cause Analysis

After investigating this issue, I've identified the root cause and why this is difficult to fix.

The Problem

The error Changes must be within bounds of SourceText occurs during linked file merging in dotnet format. When a project targets multiple frameworks:

1. The same source file is compiled separately for each TFM (e.g., net8.0, net9.0, net472)
2. Each compilation may produce different semantic analysis results
3. Each TFM's code fixer produces changes based on its semantic model
4. When dotnet format tries to merge these changes back into the single source file, the positions can conflict

Why Different TFMs Produce Different Results

The TUnit migration code fixers use SemanticModel extensively:

1. Interface detection: CollectInterfaceImplementingMethods() uses semantic model to identify interface implementations
2. Type resolution: GetSymbolInfo() resolves types differently when:
   • A type exists in one TFM but not another
   • A type resolves to different namespaces across TFMs
   • NuGet package references vary by TFM
3. Assertion rewriting: Uses semantic model to understand method calls

For example, a call to Assert.AreEqual() might:

• Resolve fully in net8.0 (symbol found)
• Fail to resolve in net472 (symbol not found, falls back to syntax check)

This produces different code transformations → different text changes → merge failure.

Attempted Fix

I attempted to make the analyzer report at deterministic syntactic locations (same for all TFMs), but this would require updating 100+ tests that expect specific diagnostic locations. The tests verify exact line/column positions.

Why This Is Hard to Fix Properly

A proper fix would require:

1. Making all code fixer logic purely syntactic (no semantic model) - but this would miss many conversion cases
2. Or making semantic analysis TFM-agnostic - very complex, may not be possible for all scenarios
3. Or having dotnet format handle linked file merging differently - upstream issue

Recommendation

The workaround documented in the issue is the correct approach:

<!-- Temporarily use single TFM for migration -->
<TargetFramework>net8.0</TargetFramework>
<!-- <TargetFrameworks>net8.0;net9.0;net10.0;net462</TargetFrameworks> -->

After migration completes, restore multi-targeting.

Additional Notes

This issue affects any Roslyn code fixer that uses semantic analysis on multi-targeted projects. It's not specific to TUnit - it's a limitation of how dotnet format merges changes for linked files.

Consider:

1. Documenting this in the migration guide
2. Adding a CLI option to run migration on a single TFM
3. Reporting upstream to dotnet/format if they have a mechanism to handle this

[thomhurst]

PR #4369 addresses this issue by adding defensive syntax-based fallbacks to the migration code fixers. When semantic analysis produces different results across TFMs (which causes the linked file merge to fail), the code fixers now fall back to deterministic syntax-based detection that produces consistent results regardless of TFM.

Once PR #4369 is merged, this issue should be resolved.