Add validation to prevent duplicate migration timestamps

[vlavrynovych]

Problem

Users can accidentally create two migrations with the same timestamp, which causes:

• Undefined execution order
• Potential overwrites in version tracking
• Confusing errors during migration runs

This is especially problematic when:

• Multiple developers work on migrations simultaneously
• Migrations are created in rapid succession
• Generated timestamps collide (same second)

Proposed Solution

Add validation that detects and prevents duplicate timestamps:

// During migration scanning
const timestamps = new Set<string>();
for (const migration of migrations) {
  if (timestamps.has(migration.version)) {
    throw new Error(
      `Duplicate migration timestamp detected: ${migration.version}\n` +
      `This can cause undefined behavior. Please rename one of:\n` +
      `  - ${migration1.filename}\n` +
      `  - ${migration2.filename}`
    );
  }
  timestamps.add(migration.version);
}

Validation Scenarios

1. At Scan Time: Check for duplicates when discovering migrations
2. At Generation Time: When creating new migration, check existing ones
3. Clear Error Messages: Tell user exactly which files conflict

Benefits

1. Prevent Data Corruption: Stop migrations before they run with undefined order
2. Early Detection: Fail fast with clear error message
3. Developer Safety: Catch mistakes before production
4. Better UX: Clear guidance on how to fix the issue

Implementation Notes

• Add to MigrationScanner service
• Include in migration template generator (#TBD)
• Show both conflicting filenames in error
• Suggest resolution: rename one migration with new timestamp
• Add test cases for duplicate detection

Related

• Part of v0.4.0 reliability improvements
• Complements Add execution summary logging for migration runs #72 (execution summary logging)
• Addresses issue found in competitive analysis (Research top 10 migration tools: features, gaps, and opportunities #74)

[vlavrynovych]

Implemented configurable duplicate timestamp detection with three modes:

• WARN (default): Logs warning but continues execution - alerts developers without blocking
• ERROR: Throws error and halts - ensures timestamp uniqueness in production
• IGNORE: Silently allows duplicates - for scenarios with external ordering guarantees

Changes

• Added DuplicateTimestampMode enum
• Added duplicateTimestampMode property to Config (default: WARN)
• Updated MigrationService.validateNoDuplicateTimestamps() to support all three modes
• Created test fixtures and added 6 integration tests
• Added comprehensive documentation to migration-settings.md

Test Results

✅ All 637 tests passing
✅ 100% code coverage maintained

The default WARN mode provides the right balance - it alerts developers to potential issues without disrupting workflow, while production environments can enforce strict uniqueness with ERROR mode.