Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

core: output order changes between builds

Aberta
  • Algo errado?
#1,183 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 3 dias

@OKAN-SOFTWARE já está trabalhando nisso.

Desde 27/10/2026.

  • #1193 de @OKAN-SOFTWARE — aberto

Avaliação

Dificuldade
3/5
Tempo estimado
1-2 dias
Facilidade para iniciantes
76/100
Tipo de issue
Bug
Clareza
Claramente especificada
Status de atividade
Ativa
Stack de tecnologia
javascript, node.js
Domínio
build-system, tooling

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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.

Linguagem predominante
JavaScript
Estrelas
70
Forks
75
Merge médio
2d 12h
PRs com merge (30d)
50

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de nodejs/doc-kit

Todas as issues de nodejs/doc-kit

Issues semelhantes

Mais issues de JavaScript

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.