core: output order changes between builds #1183

Building the same docs twice can give different files, because the order of the output depends on which worker finishes first. Two things combine:

1. createParallelWorker().stream() sends every chunk to the worker pool at once, then yields the results with Promise.race, so in whatever order the workers happen to finish.
2. The ast and ast-js generators list input files with tinyglobby's globSync, which doesn't sort, so even the order chunks are sent in can change between machines.

Generators that don't sort for themselves pass that order on. These files can change between identical builds:

• sitemap.xml (<url> order)
• llms.txt and llms-full.txt (link and page order)
• orama-db.json (document order; its ids are a separate issue)
• the legacy all.html (table of contents, sidebar and content)
• api-docs.json from json-simple
• apilinks.json (key order)

That makes diffs noisy, wastes caching, and keeps CI from comparing outputs byte for byte (today it can only compare file sizes). Generators that already sort need no change: legacy-json-all, json-all, the React all.html, jsx-ast and legacy-html.

Where to look

• packages/core/src/threading/parallel.mjs:99-137: every chunk is submitted at once, then the while (pending.size) loop yields with await Promise.race(pending) (line 126).
• packages/core/src/caching.mjs:21-24: collectAsyncGenerator keeps chunks in the order they arrive.
• packages/core/src/generators/ast/generate.mjs:117-124 and ast-js/generate.mjs:47-49: unsorted globSync results.
• packages/node-legacy/src/legacy-json-all/generate.mjs:39-52: an example of a consumer that already sorts.

How to reproduce

You don't need real workers. With a fake pool where later chunks finish first:

import createParallelWorker from './packages/core/src/threading/parallel.mjs';

const pool = {
  run: async task => {
    await new Promise(resolve => setTimeout(resolve, 50 - task.input[0] * 10));
    return task.input;
  },
};

const worker = createParallelWorker('x', { name: 'x' }, pool, {
  threads: 2,
  chunkSize: 1,
});

const out = [];
for await (const chunk of worker.stream([0, 1, 2, 3, 4], {})) out.push(...chunk);

console.log(out); // [ 4, 3, 2, 1, 0 ], expected [ 0, 1, 2, 3, 4 ]

(Run it from the repo root as an .mjs file. If the logger import gets in the way, the test file below is the easier place to try it.)

Suggested approach

1. Yield in submission order. All chunks still start at once, so it isn't any slower; the loop just awaits them in order:

   const promises = chunks.map(indices => pool.run(createTask(/* ... */)));
   
   for (const [index, promise] of promises.entries()) {
     const result = await promise;
     // keep the "Chunk N/M completed" debug log
     yield result;
   }

   The { promise, result } wrapper and the pending Set can go, and the JSDoc should say "in submission order".

2. Sort the glob results with a plain .sort(), not localeCompare, so the order doesn't depend on the machine's locale. In ast/generate.mjs, sort each pattern's results before mapping them to [child, parent], which keeps the order of config.input.

Two open PRs touch the same code, so check where they stand when you start:

• chore(core): find input files with node:fs globSync #1180 replaces tinyglobby with findFiles in packages/core/src/utils/glob.mjs. If it has landed, sort there instead, once, for every caller.
• perf: keep memory use down at low thread counts #1179 already makes the single-thread path run chunks one after another, in order. If it has landed, only the worker pool path needs the change.

How to test

In packages/core/src/threading/__tests__/parallel.test.mjs, add a case with a fake pool like the one above (no real workers needed) and assert that [0, 1, 2, 3, 4] comes back in order. For the glob sort, packages/core/src/generators/ast/__tests__/generate.test.mjs already creates a temp folder: write a few files in a jumbled order and assert the generated paths come back sorted. Run everything with node --run test.

Things to watch out for

• Fix the order once, at the source. Don't add sorting to each consumer (sitemap, llms-txt, ...).
• In ast/generate.mjs, sort before the .map into [child, parent] tuples, because .sort() on arrays would compare them as strings.
• After this, the legacy all.html follows legacy-html's order (modules sorted by name). Whether it should follow config.index like legacy-json-all is a separate question.
• orama-db.json also needs stable document ids to be reproducible: orama-db: orama-db.json changes on every build #1184.

Getting started

New to doc-kit? CONTRIBUTING.md covers setup, running the tests and adding a changeset (node --run changeset, a patch for @doc-kit/core). Leave a comment here if you'd like to take it on.