Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

core: output order changes between builds

Aperta
  • Qualcosa non va?
#1,183 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 3 giorni

@OKAN-SOFTWARE ci sta già lavorando.

Dal 27/10/2026.

  • #1193 di @OKAN-SOFTWARE — aperta

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
76/100
Tipo di issue
Bug
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
javascript, node.js
Ambito
build-system, tooling

Direzione di ricerca

Start with packages/core/src/threading/parallel.mjs and the existing test in packages/core/src/threading/__tests__/parallel.test.mjs; use the fake pool described in the issue to confirm output order. Then inspect the globSync calls in packages/core/src/generators/ast/generate.mjs and ast-js/generate.mjs, checking the status of PRs #1180 and #1179 first. Add focused tests and verify repeated builds produce stable output order.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

good first issue help wanted

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:

  • #1180 replaces tinyglobby with findFiles in packages/core/src/utils/glob.mjs. If it has landed, sort there instead, once, for every caller.
  • #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: #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.

Lingua principale
JavaScript
Stelle
70
Fork
79
Merge medio
2g 12h
PR unite (30g)
52

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di nodejs/doc-kit

Tutte le issue di nodejs/doc-kit

Issue simili

Altre issue su JavaScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.