Add execution summary logging for migration runs

[vlavrynovych]

Description

Add detailed execution summary logging that captures the complete trace of what was executed during a migration run, including both successful and failed migrations.

Requirements

Summary File Contents

• Timestamp - When the migration run started/ended
• Configuration - Config settings used (folder, rollback strategy, backup mode, etc.)
• Environment - Database handler name, MSR version
• Execution Trace:
  • Each migration attempted with timestamp
  • Success/failure status
  • Execution time per migration
  • Error messages and stack traces (if failed)
  • Actions taken (backup created, rollback triggered, etc.)
• Final Result - Overall success/failure, total time, migrations executed/failed

Configuration

config.logging.executionSummary = true; // Enable/disable (default: true for failures, false for success)
config.logging.summaryPath = './logs/migrations'; // Where to save summary files
config.logging.summaryFormat = 'json'; // 'json', 'text', or 'both'

Use Cases

• Debugging - Detailed trace when migrations fail in production
• Audit Trail - Record of all migration activity
• CI/CD - Attach summary as artifact for investigation
• Compliance - Document what changed and when

Example Summary File

{
  "timestamp": "2025-11-28T22:30:00Z",
  "msrVersion": "0.4.0",
  "handler": "PostgreSQL",
  "config": {
    "folder": "./migrations",
    "rollbackStrategy": "BACKUP",
    "backupMode": "AUTO"
  },
  "migrations": [
    {
      "name": "V202501010001_create_users",
      "timestamp": 202501010001,
      "startTime": "2025-11-28T22:30:01Z",
      "endTime": "2025-11-28T22:30:02Z",
      "duration": 1000,
      "status": "success"
    },
    {
      "name": "V202501010002_add_email_index",
      "timestamp": 202501010002,
      "startTime": "2025-11-28T22:30:02Z",
      "endTime": "2025-11-28T22:30:03Z",
      "duration": 500,
      "status": "failed",
      "error": "Duplicate key violation",
      "stackTrace": "..."
    }
  ],
  "backup": {
    "created": true,
    "path": "/backups/backup-2025-11-28.bkp",
    "size": 1024000
  },
  "rollback": {
    "triggered": true,
    "strategy": "BACKUP",
    "success": true
  },
  "result": {
    "success": false,
    "executed": 1,
    "failed": 1,
    "totalDuration": 2500
  }
}

Implementation Notes

• Create ExecutionSummaryLogger service
• Hook into existing lifecycle hooks
• Configurable via Config.logging section
• Support both JSON and human-readable text formats
• Automatic file naming with timestamp
• Option to keep only last N summaries (rotation)

Acceptance Criteria

• Summary file created for failed migrations
• Summary file configurable for successful migrations
• JSON and text format support
• Complete trace of all actions taken
• File rotation/cleanup configurable
• Integration with existing logging system

[vlavrynovych]

✅ Implementation complete and tested.

Summary:

• Execution summary logging with JSON/TEXT formats
• Hook-based architecture (ExecutionSummaryHook)
• Automatic integration when config.logging.enabled = true
• File rotation with maxFiles setting
• 100% test coverage (all tests passing)
• Documentation tracked in Update documentation for v0.4.0 release #89

Changes:

• Config.ts: Added logging property (IExecutionSummaryConfig)
• ExecutionSummaryLogger.ts: Core logging service (NEW)
• ExecutionSummaryHook.ts: Hook implementation (NEW)
• IExecutionSummary.ts: All logging interfaces (NEW)
• MigrationScriptExecutor.ts: Automatic hook integration (lines 145-149)
• ExecutionSummaryHook.test.ts: 6 comprehensive unit tests (NEW)
• ExecutionSummaryLogging.test.ts: 7 integration tests (NEW)
• ExecutionSummaryLogger.test.ts: 27 unit tests (NEW)

Key Features:

• Opt-in (default: disabled for backward compatibility)
• Seamlessly combines with user hooks via CompositeHooks
• Logs migrations, backups, rollbacks, errors, timing
• Configurable formats: JSON, TEXT, or BOTH
• File rotation prevents disk space issues
• logSuccessful flag to log only failures

Ready for v0.4.0 release.

[vlavrynovych]

✅ Feature complete and merged.

Summary:

• ExecutionSummaryLogger service and ExecutionSummaryHook implemented
• JSON, TEXT, and BOTH output formats supported
• File rotation with configurable maxFiles
• Auto-integrates when config.logging.enabled = true
• 100% test coverage (690 tests passing)

Key Features:

• Logs migrations, backups, rollbacks, errors, and timing
• Opt-in (default: disabled for backward compatibility)
• Seamlessly combines with user hooks via CompositeHooks

Ready for v0.4.0 release.
Documentation tracked in #89.