[Arthurvdv]

Summary

Fewer round trips for the fix tools, and fixes that edit several files are written completely:

• equivalenceKey is optional on apply_fix. Without it, a rule with one distinct fix is applied directly; a rule with several returns the error Ambiguous with candidates, exactly as apply_fix_all does. Both tools choose the fix through one shared CodeFixRunner.ChooseFix, and the result reports the equivalenceKey that was applied.
• dryRun on apply_fix, and a unified diff per changed file on both writers. Every apply_fix / apply_fix_all result carries changes: [{ filePath, diff, truncated }], on a dry run and after a real write, so an agent can show what changed without re-reading files. The diff is hunks only (3 context lines, no ---/+++ header), built by a hand-written line differ (UnifiedDiff: Myers O(ND) on the trimmed middle, edit-distance cap, 200 KB per-file cap cut at a line boundary). No new package.
• Every document a fix changes is written. CodeFixRunner.CollectChangesAsync diffs the code action's solution against the original (Solution.GetChanges) and is now the only place changed documents are discovered, for both tools. Side edits to other files are written too; the iterative fix-all fallback threads the whole Solution so they survive. apply_fix writes a multi-file fix all-or-nothing (GuardedFileWriter.WriteAllIfUnchangedAsync(allOrNothing: true)); apply_fix_all does the same whenever its change set includes a side edit to a file without an occurrence. A fix that adds, removes or renames files, or edits a file outside the project, is NotFound with the new reason UnsupportedFix and nothing is written.

Closes #43.

Commits

1. a33ae8d feat: apply_fix without equivalenceKey applies the single fix or returns Ambiguous
2. 835dd9b feat: write every document a fix changes
3. 061d0f6 feat: dryRun on apply_fix and unified diffs in both writers' results
4. d4554d9 fix: address review round 1 (all-or-nothing fix-all side edits, diff cap/marker edge cases, rename = UnsupportedFix, docs, tests)
5. a853b41 fix: address review round 2 (unfixed positions after a refused batch, get_fixes wording, tests)
6. 18a1c64 fix: address review round 3 (one unfixed-diagnostics rule for every unwritten change, docs)

Contract changes

• apply_fix: equivalenceKey leaves required; new parameter dryRun (default false); result is { applied, dryRun, diagnosticId, fixTitle, equivalenceKey, filePath, changes } (previously { applied, filePath, fixTitle, diagnosticId }). New error outcome Ambiguous (no key, several fixes).
• apply_fix_all: result gains changes, which describes exactly the files in filesChanged; filesChanged is now ordered by path.
• NotFound gains the reason UnsupportedFix.
• tools/list contract tests updated accordingly; titles, hints and the pinned sentences in ToolDescriptions are unchanged.

Verification

• dotnet build --configuration Release --no-incremental: 0 warnings. dotnet test --configuration Release: all tests green (378 on main, 413 on this branch).
• New tests: UnifiedDiffTests (hunk headers and counts, merge distance, CRLF and mixed terminators, no-newline marker, cap fallback, truncation), MultiDocumentFixTests (two-document fix written by both tools, add-document fix refused, stale second file writes nothing, invalid UTF-8 second file, failed second commit rolled back, stale side-edit file in fix-all, multi-file dry run), apply_fix without a key (single fix applies, AC0012 is Ambiguous), round trip of every advertised key.
• Three Sonnet review rounds (effort high) before this PR, each followed by a fix commit; round 3 found nothing blocking. The round-1 reviewer fuzzed UnifiedDiff with about 260k random inputs (an applier re-derived the new text from the hunks) and 40 large inputs through the edit-distance cap: no incorrect hunk.

Known limitations (deliberate, from the review rounds)

• Diffs are returned on real writes too and are capped per file only; a project-wide apply_fix_all over many files returns a large result. Per the issue; an aggregate cap was considered and not taken.
• In the iterative fix-all fallback (a provider without a FixAllProvider), a cross-file side edit into a file whose own diagnostics are still pending can shift their spans; the remaining-diagnostics recheck reports what was missed. No current ALCops provider edits a second document.
• The apply_fix_all all-or-nothing trigger is "a changed file without an occurrence of the rule". A cross-file fix whose second file also has an occurrence keeps the documented per-file stale handling.
• apply_fix applies the first action per equivalence key and its first ApplyChangesOperation; two different actions that both have a null key collapse into one candidate (pre-existing, documented).
• A fix that only changes line endings is written but shows an empty diff; a truncated diff keeps its original hunk headers.
• CollectChangesAsync does not see additional documents or project-level changes; a case-only rename is not detected (the Workspaces API currently cannot produce a rename at all).

🤖 Generated with Claude Code