Fix race condition in "Format edited lines" causing StringIndexOutOfBoundsException

[carstenartur]

Fix race condition in "Format edited lines" causing StringIndexOutOfBoundsException

External region calculation becomes stale between computation and formatter invocation, causing crashes in TokenManager.countLineBreaksBetween() when offsets are invalid.

Solution

Introduces DocumentDirtyTracker that maintains dirty line state within the document lifecycle:

// Instead of using stale external regions
IRegion[] regionsToFormat = changedRegions;

// Now uses atomically-tracked regions
DocumentDirtyTracker tracker = DocumentDirtyTracker.get(document);
IRegion[] dirtyRegions = tracker.getDirtyRegions();
regionsToFormat = validateRegions(dirtyRegions, document);

DocumentDirtyTracker (new)

• Tracks dirty lines via IDocumentListener, adjusts on insert/delete
• Uses documentAboutToBeChanged() to capture pre-modification state
• Thread-safe via Collections.synchronizedMap(WeakHashMap)
• Marks only start/end lines, not intermediates

CleanUpPostSaveListener

• Switches from external to tracker-based region calculation
• Adds validateRegions() with defensive bounds checking
• Clears tracker after successful format

CompilationUnitDocumentProvider

• Initializes tracker on document connect

Edge Cases Handled

• Empty regions at document end (cursor positioning)
• Multi-byte UTF-8 characters and emojis
• Rapid successive edits
• Line insertions/deletions mid-edit

Tests

• 14 comprehensive JUnit 5 test cases covering all edge cases

Original prompt

Problem

When using "Format edited lines" save action in Eclipse, users frequently encounter a StringIndexOutOfBoundsException: Index -1 out of bounds error. This is caused by a race condition where region offsets calculated externally can become stale/invalid between calculation and formatting.

See: #2499

Root Cause

The current implementation in CleanUpPostSaveListener calculates edited regions externally and passes them to the formatter. Between region calculation and formatting, the document can change, leading to invalid offsets that cause crashes in TokenManager.countLineBreaksBetween() and WrapPreparator.applyBreaksOutsideRegions().

Stack trace from the issue:

java.lang.StringIndexOutOfBoundsException: Index -1 out of bounds for length 147
    at org.eclipse.jdt.internal.formatter.TokenManager.countLineBreaksBetween(TokenManager.java:244)
    at org.eclipse.jdt.internal.formatter.linewrap.WrapPreparator.applyBreaksOutsideRegions(WrapPreparator.java:1459)

Solution

Implement a DocumentDirtyTracker that:

1. Tracks dirty lines internally - The document itself tracks which lines have been modified since the last format/save, updated atomically with each edit operation.

2. Provides always-valid regions - When the formatter requests regions to format, they are calculated from the current document state, not from stale external data.

3. Adjusts line numbers on edits - When lines are inserted or deleted, the dirty line numbers are automatically adjusted so they remain valid.

4. Add defensive bounds checking - As an additional safety measure, add bounds validation in TokenManager.countLineBreaksBetween() to prevent crashes even if invalid data somehow gets through.

Implementation Details

New class: DocumentDirtyTracker

• Implements IDocumentListener to track document changes
• Maintains a TreeSet<Integer> of dirty line numbers
• Adjusts line numbers when lines are inserted/deleted
• Provides getDirtyRegions() to get valid IRegion[] for formatting
• Uses WeakHashMap to associate trackers with documents without API changes

Modify: CleanUpPostSaveListener

• Use DocumentDirtyTracker.get(document).getDirtyRegions() instead of external region calculation
• Clear dirty lines after successful formatting

Modify: TokenManager.countLineBreaksBetween()

• Add defensive bounds checking:

public int countLineBreaksBetween(String text, int startPosition, int endPosition) {
    if (startPosition < 0 || endPosition > text.length() || startPosition >= endPosition) {
        return 0;
    }
    // ... existing code
}

Modify: CompilationUnitDocumentProvider

• Initialize DocumentDirtyTracker when document is created/connected

Benefits

• Eliminates race condition between region calculation and formatting
• Dirty lines are always consistent with current document state
• No public API changes required
• Fixes not just this bug but an entire class of potential race condition bugs

Tests to Add

Add tests in the formatter test suite that verify:

1. Formatting specific regions with non-ASCII characters (UTF-8, emojis)
2. Formatting after rapid successive edits
3. Region validity after line insertions/deletions
4. Defensive bounds checking in countLineBreaksBetween

This pull request was created from Copilot chat.

What it does

How to test

Author checklist

• I have thoroughly tested my changes
• The change is following the coding conventions
• I have signed the Eclipse Contributor Agreement (ECA)