Fix race conditions in mkdocs.yml file watcher callback

[jcouball]

Description

Fixes #48 - Prevents race conditions when mkdocs.yml is saved multiple times rapidly.

Problem

The reloadMkdocsConfig callback in extension.ts could be called multiple times rapidly if mkdocs.yml was saved multiple times quickly (e.g., during auto-save or rapid edits). Since loadMkdocsConfig() is async, this created potential race conditions:

1. Multiple config loads could be in-flight simultaneously
2. The forEach loop that refreshes diagnostics could operate on stale config data if a newer config load completes after the loop starts
3. Diagnostics could briefly show incorrect severity due to timing issues

Solution

Implemented an AsyncSerializer class that uses a semaphore pattern to ensure only one config reload happens at a time, with coalescing of rapid events.

Key Features

• Prevents concurrent executions: Only one async operation runs at a time
• Coalesces rapid calls: Multiple calls during execution result in just one re-execution
• Guarantees consistency: The most recent config is always loaded with diagnostics refreshed using that config
• Error resilient: Handles errors without breaking the serialization

Implementation Details

New Files

• src/asyncSerializer.ts - Pure business logic for serializing async operations
• src/test/unit/asyncSerializer.test.ts - Comprehensive unit tests with timing instrumentation

Modified Files

• src/extension.ts - Integrated AsyncSerializer into reloadMkdocsConfig callback

TDD Approach

This fix was developed using strict Test-Driven Development:

1. RED: Created failing unit tests that verify no concurrent executions occur
2. GREEN: Implemented AsyncSerializer with do-while semaphore pattern
3. REFACTOR: Integrated into extension.ts

Testing

• ✅ 5 new unit tests for AsyncSerializer
• ✅ All 134 tests passing (124 unit + 10 integration)
• ✅ 100% code coverage maintained
• ✅ Tests verify:
  • No concurrent executions occur
  • Multiple pending calls are coalesced
  • Immediate execution when not busy
  • Error handling doesn't break serialization
  • Sequential calls after completion work correctly

Performance Impact

• Positive: Eliminates redundant config reloads when file changes rapidly
• Negligible overhead: Simple boolean flags and do-while loop
• No blocking: Returns immediately if already executing

Related

• Resolves Prevent race conditions in mkdocs.yml file watcher callback #48
• Follows project's TDD methodology and architecture principles
• Maintains 100% test coverage requirement

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.