add mock note

Author: sirtimid

packages/repo-tools/src/test-utils/abort-signal.ts

@@ -3,6 +3,13 @@ import { vi } from 'vitest';
 /**
  * Create a mock AbortSignal that can be manually aborted.
  *
+ * This utility was created because Vitest cannot mock `AbortSignal.timeout()`.
+ * Vitest relies on @sinonjs/fake-timers for timer mocking, but fake-timers does
+ * not implement the AbortSignal.timeout API, so we cannot use Vitest's timer
+ * mocking to test timeout behavior. This mock allows us to manually trigger
+ * abort events in tests to simulate timeout scenarios.
+ * https://github.com/vitest-dev/vitest/issues/3088
+ *
  * @param timeoutMs - The timeout value (stored for verification).
  * @returns A mock AbortSignal.
  */