Random CI failures due to light theme color differences

[ST-DDT]

I have random/flaky (~1%) CI failures in one of my actions:
https://github.com/faker-js/faker/actions/runs/27549969244/job/81433308467
What could be the cause of different "light" colors? (vitest md->html snapshot test)

I use vitepress's markdown renderer directly since I have to use the markdown inside a Vue component of mine.

export async function initMarkdownRenderer(): Promise<void> {
  markdown ??= await createMarkdownRenderer(
    FILE_PATH_API_DOCS,
    vitepressConfig.markdown, // Empty/default
    '/'
  );
}

It looks like a race condition inside the markdown/vitepress setup, but I'm not sure where/what.
In case of the error, the code block seems to use less colors than the normal snapshots.

Does anybody know what could cause this/where to look? I already asked over at vitepress, but they didn't know either.

[MILLERMARRU]

This looks like a race in your own caching line rather than in Shiki or VitePress's highlighter itself:

markdown ??= await createMarkdownRenderer(...)

??= isn't atomic across concurrent async calls. If initMarkdownRenderer() gets invoked more than once before the first call resolves (parallel test files in the same worker, Promise.all across doc pages, whatever your test runner's concurrency model is), every one of those calls reads markdown as still undefined before any assignment has happened, and each one goes ahead and calls createMarkdownRenderer() independently. You end up with multiple concurrent Shiki highlighter instances being created against the same theme files, and depending on timing, whichever promise resolves last is the one that wins the assignment, while the others' work is silently discarded. Shiki's own guidance is to treat a highlighter as a long-lived singleton and reuse it rather than creating fresh ones, precisely because concurrent/repeated creation isn't something it optimizes or guards against for you, so multiple in-flight creations racing each other lines up with "fewer colors" appearing in the flaky runs, one of the concurrent creations plausibly resolves before its theme/grammar loading is fully settled.

The fix is to cache the promise itself, not the awaited value, so every caller gets the same in-flight (or resolved) promise instead of each one racing to create their own:

let markdownPromise: Promise<MarkdownRenderer> | undefined;

export function initMarkdownRenderer(): Promise<MarkdownRenderer> {
  markdownPromise ??= createMarkdownRenderer(
    FILE_PATH_API_DOCS,
    vitepressConfig.markdown,
    '/'
  );
  return markdownPromise;
}

Here ??= is safe because it's evaluated synchronously, the promise gets created and assigned in one tick regardless of how many callers show up before it resolves, so every concurrent caller awaits the exact same promise instead of triggering a fresh createMarkdownRenderer() each time. That should turn the ~1% flake into 0%, since there's only ever one highlighter creation happening no matter how many callers race to initialize it.

[ST-DDT]

Interesting idea, I will try that.

We do call the init independently of loops

https://github.com/search?q=repo%3Afaker-js%2Ffaker+initMarkdownRenderer%28%29&type=code

but vitest may multi-thread the tests/re-initializes the imports. Though I'm not sure whether storing the promise will help in either case.