@doc-kit/core 1.0.1 → 1.2.0

package/src/generators/json-all/schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://doc-kit.nodejs.org/schemas/api-doc-all/1.0.1.json",
+  "title": "Bundle",
+  "description": "Every document of a documentation set, as emitted by the doc-kit `json-all` generator",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "The URL of the schema this bundle conforms to. Its last path segment is the schema version."
+    },
+    "documents": {
+      "type": "array",
+      "items": {
+        "$ref": "https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json"
+      },
+      "description": "The documents, in the order of the configured index, then by id."
+    }
+  },
+  "required": ["$schema", "documents"],
+  "additionalProperties": false
+}

package/src/generators/json-all/types.d.ts

@@ -0,0 +1,20 @@
+import type { Document } from '../json/generated/schema';
+
+/**
+ * Every document of a documentation set
+ */
+export interface Bundle {
+  /** The URL of the schema the bundle conforms to */
+  $schema: string;
+  documents: Array<Document>;
+}
+
+export interface Configuration {
+  /** Where the schema is published; `{schemaVersion}` is filled in */
+  schemaURL: string;
+}
+
+export type Generator = GeneratorMetadata<
+  Configuration,
+  Generate<Array<Document>, Promise<Bundle>>
+>;

package/src/generators/json-simple/generate.mjs

@@ -5,7 +5,7 @@ import { join } from 'node:path';
 import { remove } from 'unist-util-remove';
 
 import getConfig from '#utils/configuration/index.mjs';
-import { writeFile } from '#utils/file.mjs';
+import { writeJSON } from '#utils/file.mjs';
 import { UNIST } from '#utils/queries/index.mjs';
 
 /**
@@ -21,12 +21,7 @@ export async function generate(input) {
   );
 
   if (config.output) {
-    // Writes all the API docs stringified content into one file
-    // Note: The full JSON generator in the future will create one JSON file per top-level API doc file
-    await writeFile(
-      join(config.output, 'api-docs.json'),
-      config.minify ? JSON.stringify(input) : JSON.stringify(input, null, 2)
-    );
+    await writeJSON(join(config.output, 'api-docs.json'), input, config.minify);
   }
 
   return input;

package/src/generators/loader.mjs

@@ -3,6 +3,8 @@
 import { isAbsolute } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
+import { enforceArray } from '#utils/array.mjs';
+
 import { allGenerators } from './index.mjs';
 
 /**
@@ -67,7 +69,7 @@ export const loadGenerator = async specifier => {
 
 /**
  * Loads the given generators plus the transitive closure of their
- * dependencies (via `dependsOn`).
+ * dependencies (via `dependsOn`) and dependents (via `dependent`).
  *
  * @param {string[]} targets - Shorthand names, paths, or import specifiers
  * @returns {Promise<Map<string, GeneratorMetadata>>} Loaded generators keyed
@@ -87,8 +89,11 @@ export const loadGenerators = async targets => {
     const generator = await loadGenerator(specifier);
     generators.set(specifier, generator);
 
-    if (generator.dependsOn) {
-      queue.push(resolveGeneratorSpecifier(generator.dependsOn));
+    for (const related of [
+      ...enforceArray(generator.dependsOn ?? []),
+      ...enforceArray(generator.dependent ?? []),
+    ]) {
+      queue.push(resolveGeneratorSpecifier(related));
     }
   }
 

package/src/generators/metadata/maps/mdn.json

@@ -421,6 +421,7 @@
   "idbkeyrange": "https://developer.mozilla.org/docs/Web/API/IDBKeyRange",
   "idbobjectstore": "https://developer.mozilla.org/docs/Web/API/IDBObjectStore",
   "idbopendbrequest": "https://developer.mozilla.org/docs/Web/API/IDBOpenDBRequest",
+  "idbrecord": "https://developer.mozilla.org/docs/Web/API/IDBRecord",
   "idbrequest": "https://developer.mozilla.org/docs/Web/API/IDBRequest",
   "idbtransaction": "https://developer.mozilla.org/docs/Web/API/IDBTransaction",
   "idbversionchangeevent": "https://developer.mozilla.org/docs/Web/API/IDBVersionChangeEvent",
@@ -442,6 +443,7 @@
   "inputdeviceinfo": "https://developer.mozilla.org/docs/Web/API/InputDeviceInfo",
   "inputevent": "https://developer.mozilla.org/docs/Web/API/InputEvent",
   "installevent": "https://developer.mozilla.org/docs/Web/API/InstallEvent",
+  "interactioncontentfulpaint": "https://developer.mozilla.org/docs/Web/API/InteractionContentfulPaint",
   "interestevent": "https://developer.mozilla.org/docs/Web/API/InterestEvent",
   "intersectionobserver": "https://developer.mozilla.org/docs/Web/API/IntersectionObserver",
   "intersectionobserverentry": "https://developer.mozilla.org/docs/Web/API/IntersectionObserverEntry",
@@ -452,6 +454,7 @@
   "keyboardlayoutmap": "https://developer.mozilla.org/docs/Web/API/KeyboardLayoutMap",
   "keyframeeffect": "https://developer.mozilla.org/docs/Web/API/KeyframeEffect",
   "languagedetector": "https://developer.mozilla.org/docs/Web/API/LanguageDetector",
+  "languagemodel": "https://developer.mozilla.org/docs/Web/API/LanguageModel",
   "largestcontentfulpaint": "https://developer.mozilla.org/docs/Web/API/LargestContentfulPaint",
   "launchparams": "https://developer.mozilla.org/docs/Web/API/LaunchParams",
   "launchqueue": "https://developer.mozilla.org/docs/Web/API/LaunchQueue",
@@ -589,7 +592,9 @@
   "performanceresourcetiming": "https://developer.mozilla.org/docs/Web/API/PerformanceResourceTiming",
   "performancescripttiming": "https://developer.mozilla.org/docs/Web/API/PerformanceScriptTiming",
   "performanceservertiming": "https://developer.mozilla.org/docs/Web/API/PerformanceServerTiming",
+  "performancesoftnavigation": "https://developer.mozilla.org/docs/Web/API/PerformanceSoftNavigation",
   "performancetiming": "https://developer.mozilla.org/docs/Web/API/PerformanceTiming",
+  "performancetimingconfidence": "https://developer.mozilla.org/docs/Web/API/PerformanceTimingConfidence",
   "periodicsyncevent": "https://developer.mozilla.org/docs/Web/API/PeriodicSyncEvent",
   "periodicsyncmanager": "https://developer.mozilla.org/docs/Web/API/PeriodicSyncManager",
   "periodicwave": "https://developer.mozilla.org/docs/Web/API/PeriodicWave",
@@ -636,6 +641,7 @@
   "rtcerror": "https://developer.mozilla.org/docs/Web/API/RTCError",
   "rtcerrorevent": "https://developer.mozilla.org/docs/Web/API/RTCErrorEvent",
   "rtcicecandidate": "https://developer.mozilla.org/docs/Web/API/RTCIceCandidate",
+  "rtcicecandidatepair": "https://developer.mozilla.org/docs/Web/API/RTCIceCandidatePair",
   "rtcicetransport": "https://developer.mozilla.org/docs/Web/API/RTCIceTransport",
   "rtcidentityassertion": "https://developer.mozilla.org/docs/Web/API/RTCIdentityAssertion",
   "rtcpeerconnection": "https://developer.mozilla.org/docs/Web/API/RTCPeerConnection",
@@ -672,7 +678,6 @@
   "restrictiontarget": "https://developer.mozilla.org/docs/Web/API/RestrictionTarget",
   "svgaelement": "https://developer.mozilla.org/docs/Web/API/SVGAElement",
   "svgangle": "https://developer.mozilla.org/docs/Web/API/SVGAngle",
-  "svganimatecolorelement": "https://developer.mozilla.org/docs/Web/API/SVGAnimateColorElement",
   "svganimateelement": "https://developer.mozilla.org/docs/Web/API/SVGAnimateElement",
   "svganimatemotionelement": "https://developer.mozilla.org/docs/Web/API/SVGAnimateMotionElement",
   "svganimatetransformelement": "https://developer.mozilla.org/docs/Web/API/SVGAnimateTransformElement",
@@ -749,7 +754,6 @@
   "svgradialgradientelement": "https://developer.mozilla.org/docs/Web/API/SVGRadialGradientElement",
   "svgrect": "https://developer.mozilla.org/docs/Web/API/SVGRect",
   "svgrectelement": "https://developer.mozilla.org/docs/Web/API/SVGRectElement",
-  "svgrenderingintent": "https://developer.mozilla.org/docs/Web/API/SVGRenderingIntent",
   "svgsvgelement": "https://developer.mozilla.org/docs/Web/API/SVGSVGElement",
   "svgscriptelement": "https://developer.mozilla.org/docs/Web/API/SVGScriptElement",
   "svgsetelement": "https://developer.mozilla.org/docs/Web/API/SVGSetElement",
@@ -947,8 +951,10 @@
   "webtransport": "https://developer.mozilla.org/docs/Web/API/WebTransport",
   "webtransportbidirectionalstream": "https://developer.mozilla.org/docs/Web/API/WebTransportBidirectionalStream",
   "webtransportdatagramduplexstream": "https://developer.mozilla.org/docs/Web/API/WebTransportDatagramDuplexStream",
+  "webtransportdatagramswritable": "https://developer.mozilla.org/docs/Web/API/WebTransportDatagramsWritable",
   "webtransporterror": "https://developer.mozilla.org/docs/Web/API/WebTransportError",
   "webtransportreceivestream": "https://developer.mozilla.org/docs/Web/API/WebTransportReceiveStream",
+  "webtransportsendgroup": "https://developer.mozilla.org/docs/Web/API/WebTransportSendGroup",
   "webtransportsendstream": "https://developer.mozilla.org/docs/Web/API/WebTransportSendStream",
   "wheelevent": "https://developer.mozilla.org/docs/Web/API/WheelEvent",
   "window": "https://developer.mozilla.org/docs/Web/API/Window",
@@ -1014,6 +1020,7 @@
   "xrview": "https://developer.mozilla.org/docs/Web/API/XRView",
   "xrviewerpose": "https://developer.mozilla.org/docs/Web/API/XRViewerPose",
   "xrviewport": "https://developer.mozilla.org/docs/Web/API/XRViewport",
+  "xrvisibilitymaskchangeevent": "https://developer.mozilla.org/docs/Web/API/XRVisibilityMaskChangeEvent",
   "xrwebglbinding": "https://developer.mozilla.org/docs/Web/API/XRWebGLBinding",
   "xrwebgldepthinformation": "https://developer.mozilla.org/docs/Web/API/XRWebGLDepthInformation",
   "xrwebgllayer": "https://developer.mozilla.org/docs/Web/API/XRWebGLLayer",

package/src/generators/metadata/types.d.ts

@@ -97,6 +97,11 @@ export interface HeadingData extends Data {
    * from the ToC while still rendering on the page.
    */
   isOverload?: boolean;
+  /**
+   * The slug of the first heading of the overloaded function this heading is
+   * an overload of. Set alongside `isOverload`.
+   */
+  overloadOf?: string;
 }
 
 /**
@@ -120,6 +125,23 @@ export interface StabilityData extends Data {
  */
 export type StabilityNode = NodeWithData<Blockquote, StabilityData>;
 
+/**
+ * Describes a chunk page: a section of a module rendered as a page of its own
+ * (see the `section-pages` generator). Present on every entry of a chunk page.
+ */
+export interface ChunkInfo {
+  /** The `api` of the module the chunk was split from */
+  api: string;
+  /** The `path` of the module the chunk was split from */
+  path: string;
+  /** The section's anchor on the full module page */
+  slug: string;
+  /** The chunk's position within the module, in document order */
+  index: number;
+  /** The original depth of the chunk's heading */
+  depth: number;
+}
+
 /**
  * Complete metadata entry for a single API documentation element.
  *
@@ -136,6 +158,8 @@ export interface MetadataEntry extends YAMLProperties {
   synthetic?: boolean;
   /** Whether this page was authored as MDX (JSX-in-Markdown). */
   mdx?: boolean;
+  /** Set when this entry belongs to a chunk page rather than a full page. */
+  chunk?: ChunkInfo;
   /** Processed heading with metadata */
   heading: HeadingNode;
   /** Stability classification information */

package/src/generators/pipeline.mjs

@@ -0,0 +1,169 @@
+'use strict';
+
+import { enforceArray } from '#utils/array.mjs';
+
+import { resolveGeneratorSpecifier } from './loader.mjs';
+
+/**
+ * The resolved specifiers of the generators a generator is delivered through.
+ *
+ * @param {GeneratorMetadata | undefined} generator
+ * @returns {string[]}
+ */
+const dependentsOf = generator =>
+  enforceArray(generator?.dependent ?? []).map(resolveGeneratorSpecifier);
+
+/**
+ * Collects the generators reached from the given ones through `dependsOn`.
+ *
+ * @param {string[]} specifiers - Resolved generator specifiers
+ * @param {Map<string, GeneratorMetadata>} generators - Loaded generators
+ * @returns {Set<string>}
+ */
+const dependencyClosure = (specifiers, generators) => {
+  const closure = new Set();
+  const stack = [...specifiers];
+
+  while (stack.length > 0) {
+    const specifier = stack.pop();
+
+    if (closure.has(specifier)) {
+      continue;
+    }
+
+    closure.add(specifier);
+
+    const { dependsOn } = generators.get(specifier) ?? {};
+
+    if (dependsOn) {
+      stack.push(resolveGeneratorSpecifier(dependsOn));
+    }
+  }
+
+  return closure;
+};
+
+/**
+ * Splices a generator into a dependent's pipeline: walking from the dependent
+ * up its dependency chain, the first generator that consumes the splicing
+ * generator's own input is rewired to consume the splicing generator instead.
+ *
+ * @param {string} specifier - The generator to splice in
+ * @param {string} dependent - The pipeline to splice it into
+ * @param {Map<string, string | undefined>} inputOf - Effective inputs, mutated
+ * @param {string} name - The splicing generator's name, for errors
+ */
+const splice = (specifier, dependent, inputOf, name) => {
+  const upstream = inputOf.get(specifier);
+  const visited = new Set();
+
+  let current = dependent;
+
+  while (current !== undefined && current !== specifier) {
+    if (visited.has(current)) {
+      break;
+    }
+
+    visited.add(current);
+
+    if (inputOf.get(current) === upstream) {
+      inputOf.set(current, specifier);
+      return;
+    }
+
+    current = inputOf.get(current);
+  }
+
+  throw new Error(
+    `Generator "${name}" declares "${dependent}" as its dependent, but ` +
+      `nothing in that pipeline consumes "${upstream ?? 'no input'}", so ` +
+      'there is nowhere to splice it in.'
+  );
+};
+
+/**
+ * Follows a generator's `dependent` links to the generators that finally
+ * deliver its output. When some of its dependents are already part of the
+ * run, only those deliver it; otherwise all of them do.
+ *
+ * @param {string} specifier - Resolved generator specifier
+ * @param {Map<string, GeneratorMetadata>} generators - Loaded generators
+ * @param {Set<string>} requested - Generators already part of the run
+ * @param {Set<string>} [seen] - Guards against dependent cycles
+ * @returns {string[]} Resolved specifiers of the terminal generators
+ */
+const resolveTerminals = (
+  specifier,
+  generators,
+  requested,
+  seen = new Set()
+) => {
+  if (seen.has(specifier)) {
+    return [];
+  }
+
+  seen.add(specifier);
+
+  const dependents = dependentsOf(generators.get(specifier));
+
+  if (dependents.length === 0) {
+    return [specifier];
+  }
+
+  const active = dependents.filter(dependent => requested.has(dependent));
+
+  return (active.length > 0 ? active : dependents).flatMap(dependent =>
+    resolveTerminals(dependent, generators, requested, seen)
+  );
+};
+
+/**
+ * Resolves the effective pipeline for a run: which generator each generator
+ * reads its input from, and which generators the run finally collects.
+ *
+ * By default a generator reads from its `dependsOn`. A generator that declares
+ * one or more `dependent`s is spliced into each dependent's pipeline (see
+ * {@link splice}). Several generators may splice at the same point; each later
+ * one is inserted upstream of the earlier ones, forming a chain.
+ *
+ * A requested generator that declares dependents is delivered through them,
+ * so the run collects their output rather than the generator's own: through
+ * the dependents that are already part of the run when there are any, and
+ * through all of them otherwise.
+ *
+ * @param {string[]} targets - Requested targets, as resolved specifiers
+ * @param {Map<string, GeneratorMetadata>} generators - Loaded generators,
+ * including every dependency and dependent of the targets
+ * @returns {{ targets: string[], inputOf: Map<string, string | undefined> }}
+ * The generators to collect, and each generator's effective input generator
+ */
+export const resolvePipeline = (targets, generators) => {
+  /** @type {Map<string, string | undefined>} */
+  const inputOf = new Map();
+
+  for (const [specifier, { dependsOn }] of generators) {
+    inputOf.set(
+      specifier,
+      dependsOn ? resolveGeneratorSpecifier(dependsOn) : undefined
+    );
+  }
+
+  for (const [specifier, generator] of generators) {
+    for (const dependent of dependentsOf(generator)) {
+      splice(specifier, dependent, inputOf, generator.name);
+    }
+  }
+
+  const requested = dependencyClosure(targets, generators);
+  const collected = [];
+
+  for (const target of targets) {
+    for (const terminal of resolveTerminals(target, generators, requested)) {
+      if (!collected.includes(terminal)) {
+        collected.push(terminal);
+      }
+    }
+  }
+
+  return { targets: collected, inputOf };
+};

package/src/generators/types.d.ts

@@ -97,6 +97,26 @@ declare global {
      */
     dependsOn: string | undefined;
 
+    /**
+     * The generator(s) this generator's output is delivered through, declared
+     * as import specifiers. This is the inverse of `dependsOn`: rather than
+     * pulling a dependency in, it pushes this generator into another
+     * generator's pipeline.
+     *
+     * The orchestrator splices this generator in front of the first generator
+     * in each dependent's dependency chain that consumes the same `dependsOn`
+     * as this one. For example, a generator with
+     * `dependsOn: '@doc-kit/core/metadata'` and
+     * `dependent: '@doc-kit/generator-react/html'` is inserted between
+     * `metadata` and `jsx-ast` (the consumer of `metadata` on the way to
+     * `html`), so its output is what `jsx-ast` — and therefore `html` — sees.
+     *
+     * Requesting a generator that declares dependents runs them as well, and
+     * the run's result is their output: when some of the dependents are
+     * already part of the run, only those; otherwise all of them.
+     */
+    dependent?: string | string[];
+
     /**
      * Generators are abstract and the different generators have different sort of inputs and outputs.
      * For example, a MDX generator would take the raw AST and output MDX with React Components;

package/src/generators.mjs

@@ -5,6 +5,7 @@ import {
   loadGenerators,
   resolveGeneratorSpecifier,
 } from './generators/loader.mjs';
+import { resolvePipeline } from './generators/pipeline.mjs';
 import logger from './logger/index.mjs';
 import createWorkerPool from './threading/index.mjs';
 import createParallelWorker from './threading/parallel.mjs';
@@ -44,9 +45,12 @@ const createGenerator = () => {
    *
    * @param {string} specifier - Resolved generator specifier to schedule
    * @param {Map<string, GeneratorMetadata>} generators - Loaded generators
+   * @param {Map<string, string | undefined>} inputOf - Each generator's
+   * effective input generator (its dependency, unless another generator was
+   * spliced in front of it via `dependent`)
    * @param {import('./utils/configuration/types').Configuration} configuration - Runtime options
    */
-  const scheduleGenerator = (specifier, generators, configuration) => {
+  const scheduleGenerator = (specifier, generators, inputOf, configuration) => {
     if (cache.has(specifier)) {
       return;
     }
@@ -54,12 +58,11 @@ const createGenerator = () => {
     const generator = generators.get(specifier);
     const { name, generate, hasParallelProcessor } = generator;
 
-    const dependsOn =
-      generator.dependsOn && resolveGeneratorSpecifier(generator.dependsOn);
+    const dependsOn = inputOf.get(specifier);
 
     // Schedule dependency first
     if (dependsOn && !cache.has(dependsOn)) {
-      scheduleGenerator(dependsOn, generators, configuration);
+      scheduleGenerator(dependsOn, generators, inputOf, configuration);
     }
 
     generatorsLogger.debug(`Scheduling "${name}"`, {
@@ -104,8 +107,16 @@ const createGenerator = () => {
 
     // Resolve shorthand names and load the full dependency closure up front,
     // so scheduling below is fully synchronous.
-    const targets = target.map(resolveGeneratorSpecifier);
-    const generators = await loadGenerators(targets);
+    const generators = await loadGenerators(
+      target.map(resolveGeneratorSpecifier)
+    );
+
+    // Work out who reads from whom once generators declaring a `dependent`
+    // have been spliced in, and which generators the run finally collects.
+    const { targets, inputOf } = resolvePipeline(
+      target.map(resolveGeneratorSpecifier),
+      generators
+    );
 
     generatorsLogger.debug(`Starting pipeline`, {
       generators: targets.join(', '),
@@ -114,18 +125,14 @@ const createGenerator = () => {
 
     // Compute consumer counts up front so dependencies can be evicted as soon
     // as their last consumer runs (must be ready before any generator starts).
-    cache.populateConsumerCounts(targets, specifier => {
-      const { dependsOn } = generators.get(specifier);
-
-      return dependsOn && resolveGeneratorSpecifier(dependsOn);
-    });
+    cache.populateConsumerCounts(targets, specifier => inputOf.get(specifier));
 
     // Create worker pool
     pool = createWorkerPool(threads);
 
     // Schedule all generators
     for (const specifier of targets) {
-      scheduleGenerator(specifier, generators, configuration);
+      scheduleGenerator(specifier, generators, inputOf, configuration);
     }
 
     // Start all collections in parallel (don't await sequentially). Consuming

package/src/logger/logger.mjs

@@ -165,6 +165,13 @@ export const createLogger = (
     }
   };
 
+  /**
+   * Gets the current log level for this logger instance.
+   *
+   * @returns {number} The current numeric log level
+   */
+  const getLogLevel = () => currentLevel;
+
   return {
     info,
     warn,
@@ -173,5 +180,6 @@ export const createLogger = (
     debug,
     child,
     setLogLevel,
+    getLogLevel,
   };
 };

package/src/parsers/markdown.mjs

@@ -22,9 +22,7 @@ const NODE_LTS_VERSION_REGEX = /Long Term Support/i;
 export const parseChangelog = async path => {
   const changelog = await loadFromURL(path);
 
-  const nodeMajors = Array.from(changelog.matchAll(NODE_VERSIONS_REGEX));
-
-  return nodeMajors.map(match => ({
+  return Array.from(changelog.matchAll(NODE_VERSIONS_REGEX), match => ({
     version: coerce(match[1]),
     isLts: NODE_LTS_VERSION_REGEX.test(match[2]),
   }));
@@ -43,7 +41,8 @@ export const parseIndex = async path => {
 
   const index = await loadFromURL(path);
 
-  const items = Array.from(index.matchAll(LIST_ITEM_REGEX));
-
-  return items.map(([, section, api]) => ({ section, api }));
+  return Array.from(index.matchAll(LIST_ITEM_REGEX), ([, section, api]) => ({
+    section,
+    api,
+  }));
 };

package/src/threading/chunk-worker.mjs

@@ -1,6 +1,13 @@
+import { workerData } from 'node:worker_threads';
+
 import { loadGenerator } from '#generators/loader.mjs';
+import logger from '#logger/index.mjs';
 import { setConfig } from '#utils/configuration/index.mjs';
 
+if (workerData?.logLevel !== undefined) {
+  logger.setLogLevel(workerData.logLevel);
+}
+
 /**
  * Processes a chunk of items using the specified generator's processChunk method.
  * This is the worker entry point for Piscina.

package/src/threading/index.mjs

@@ -23,5 +23,6 @@ export default function createWorkerPool(threads) {
     minThreads: 0,
     maxThreads: threads,
     idleTimeout: 1_000,
+    workerData: { logLevel: logger.getLogLevel() },
   });
 }

package/src/utils/configuration/constants.mjs

@@ -0,0 +1,13 @@
+'use strict';
+
+/**
+ * The default `threads` ceiling. Each worker that highlights code holds Shiki's
+ * grammars and regex engine (~300MB) on top of the pages it is building, so
+ * past a few threads memory, not CPU, is what runs out. `--threads` raises it.
+ */
+export const DEFAULT_MAX_THREADS = 4;
+
+/**
+ * The default number of items each worker task processes.
+ */
+export const DEFAULT_CHUNK_SIZE = 10;

package/src/utils/configuration/index.mjs

@@ -18,6 +18,8 @@ import { enforceArray } from '#utils/array.mjs';
 import { leftHandAssign } from '#utils/generators.mjs';
 import { deepMerge } from '#utils/misc.mjs';
 
+import { DEFAULT_CHUNK_SIZE, DEFAULT_MAX_THREADS } from './constants.mjs';
+
 const configExplorer = cosmiconfig('doc-kit');
 
 /**
@@ -68,8 +70,11 @@ export const getDefaultConfig = (generators, config) =>
       // riscv64 with sv39. Running multiple generators that use wasm in
       // parallel could cause failures to allocate new wasm instance.
       // See also https://github.com/nodejs/node/pull/60591
-      threads: process.arch === 'riscv64' ? 1 : cpus().length,
-      chunkSize: 10,
+      threads:
+        process.arch === 'riscv64'
+          ? 1
+          : Math.min(cpus().length, DEFAULT_MAX_THREADS),
+      chunkSize: DEFAULT_CHUNK_SIZE,
     })
   );
 

package/src/utils/file.mjs

@@ -18,3 +18,13 @@ export const writeFile = (file, ...args) =>
   fs
     .mkdir(dirname(file), { recursive: true })
     .then(() => fs.writeFile(file, ...args));
+
+/**
+ * Writes a value as JSON
+ *
+ * @param {string} file
+ * @param {unknown} value
+ * @param {boolean} [minify]
+ */
+export const writeJSON = (file, value, minify = false) =>
+  writeFile(file, JSON.stringify(value, null, minify ? 0 : 2));

package/src/utils/hierarchy.mjs

@@ -0,0 +1,50 @@
+'use strict';
+
+/**
+ * A node in the entry hierarchy.
+ *
+ * @typedef {object} HierarchizedEntry
+ * @property {import('../generators/metadata/types').MetadataEntry} entry The metadata entry this node wraps
+ * @property {Array<HierarchizedEntry>} children Entries nested under this one, by heading depth
+ */
+
+/**
+ * Finds the closest preceding node whose heading is shallower than the
+ * entry's, which is the entry's parent.
+ *
+ * @param {import('../generators/metadata/types').MetadataEntry} entry The entry to find a parent for
+ * @param {Array<HierarchizedEntry>} nodes Wrapper nodes, index-aligned with the entries
+ * @param {number} startIdx The index to search backwards from
+ * @returns {HierarchizedEntry | undefined} The parent, or `undefined` when no shallower entry precedes it
+ */
+export const findParent = (entry, nodes, startIdx) => {
+  for (let i = startIdx; i >= 0; i--) {
+    if (nodes[i].entry.heading.depth < entry.heading.depth) {
+      return nodes[i];
+    }
+  }
+
+  return undefined;
+};
+
+/**
+ * @param {Array<import('../generators/metadata/types').MetadataEntry>} entries Entries in document order
+ * @returns {Array<HierarchizedEntry>} The root nodes
+ */
+export const buildHierarchy = entries => {
+  const roots = [];
+
+  // Wrapper nodes, index-aligned with `entries`
+  const nodes = entries.map(entry => ({ entry, children: [] }));
+
+  nodes.forEach((node, i) => {
+    const parent =
+      node.entry.heading.depth <= 1
+        ? undefined
+        : findParent(node.entry, nodes, i - 1);
+
+    (parent?.children ?? roots).push(node);
+  });
+
+  return roots;
+};