@doc-kit/core 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @doc-kit/core
 
+## 1.1.0
+
+### Minor Changes
+
+- [#1090](https://github.com/nodejs/doc-kit/pull/1090) [`0a9dc37`](https://github.com/nodejs/doc-kit/commit/0a9dc37dc96f8044c76c3ca9b35e97895a87d1fd) Thanks [@avivkeller](https://github.com/avivkeller)! - perf: build the site one page at a time, and `all.html` from the module pages
+
+- [#1057](https://github.com/nodejs/doc-kit/pull/1057) [`da5d8e6`](https://github.com/nodejs/doc-kit/commit/da5d8e63d0d33fe7a95c46afb8d5140d576827b4) Thanks [@avivkeller](https://github.com/avivkeller)! - feat: `dependent` generators and the `section-pages` generator
+
+## 1.0.1
+
+### Patch Changes
+
+- [#1023](https://github.com/nodejs/doc-kit/pull/1023) [`27a412a`](https://github.com/nodejs/doc-kit/commit/27a412ac35ab06e977b03b559e6525c0c5c5356c) Thanks [@btea](https://github.com/btea)! - Fix empty paragraphs in API docs when a typed parameter list contains trailing non-parameter items
+
+  When a loose markdown list in the API docs starts with typed parameters (e.g. `actual`, `expected`, `Returns`) but also contains plain prose bullets (e.g. algorithm complexity notes), the entire list was previously treated as a parameter signature table. The non-parameter items had no name or type, causing them to render as empty `<section>` blocks on the built site.
+
+  The fix splits the list at the first non-parameter item: typed items become the `FunctionSignature` table, and the remaining items render as regular markdown content.
+
+- [#1045](https://github.com/nodejs/doc-kit/pull/1045) [`4a22c85`](https://github.com/nodejs/doc-kit/commit/4a22c85dca917f52c773aba084191da7c622687e) Thanks [@avivkeller](https://github.com/avivkeller)! - MDX nodes in the HTML-string pipelines are now dropped, and do not crash.
+
+- [#1049](https://github.com/nodejs/doc-kit/pull/1049) [`8cc1fd0`](https://github.com/nodejs/doc-kit/commit/8cc1fd010ac38b16dd3c9bcd422c0ce0e5eb483d) Thanks [@avivkeller](https://github.com/avivkeller)! - Render markdown summaries as markup instead of as their source
+
 ## 1.0.0
 
 ### Major Changes

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@doc-kit/core",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "The doc-kit engine: the pipeline and shared APIs that power the doc-kit generators and CLI",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nodejs/doc-kit.git",
     "directory": "packages/core"
   },
+  "license": "MIT",
   "main": "./src/generators.mjs",
   "exports": {
     ".": "./src/generators.mjs",
@@ -18,7 +19,19 @@
     "./package.json": "./package.json",
     "./shiki.config.mjs": "./shiki.config.mjs",
     "./src/*": "./src/*",
-    "./*": "./src/*"
+    "./*": [
+      "./src/*",
+      "./src/*.d.ts"
+    ]
+  },
+  "imports": {
+    "#generators/*": "./src/generators/*",
+    "#logger/*": "./src/logger/*",
+    "#parsers/*": [
+      "./src/parsers/*",
+      "./src/parsers/*.d.ts"
+    ],
+    "#utils/*": "./src/utils/*"
   },
   "files": [
     "src",
@@ -31,7 +44,7 @@
   ],
   "dependencies": {
     "@actions/core": "^3.0.0",
-    "@node-core/rehype-shiki": "^1.4.3",
+    "@node-core/rehype-shiki": "^1.5.0",
     "@swc/html-wasm": "^1.15.46",
     "@swc/wasm": "^1.15.46",
     "acorn": "^8.17.0",
@@ -40,7 +53,7 @@
     "github-slugger": "^2.0.0",
     "glob-parent": "^6.0.2",
     "hastscript": "^9.0.1",
-    "piscina": "^5.3.0",
+    "piscina": "^5.3.1",
     "rehype-stringify": "^10.0.1",
     "remark-gfm": "^4.0.1",
     "remark-mdx": "^3.1.1",
@@ -48,7 +61,7 @@
     "remark-rehype": "^11.1.2",
     "remark-stringify": "^11.0.0",
     "semver": "^7.8.5",
-    "shiki": "^4.3.0",
+    "shiki": "^4.4.3",
     "tinyglobby": "^0.2.17",
     "unified": "^11.0.5",
     "unist-builder": "^4.0.0",
@@ -64,9 +77,9 @@
     "hast-util-to-string": "^3.0.1"
   },
   "peerDependencies": {
-    "@node-core/doc-kit": "2.0.0",
-    "@node-core/doc-kit-legacy": "1.0.0",
-    "@doc-kit/generator-react": "0.1.0"
+    "@node-core/doc-kit": ">=2.0.0",
+    "@node-core/doc-kit-legacy": ">=1.0.0",
+    "@doc-kit/generator-react": ">=0.1.0"
   },
   "peerDependenciesMeta": {
     "@node-core/doc-kit": {

package/src/generators/ast/generate.mjs

@@ -7,11 +7,12 @@ import globParent from 'glob-parent';
 import { globSync } from 'tinyglobby';
 import { parse as parseYaml } from 'yaml';
 
+import getConfig from '#utils/configuration/index.mjs';
+import { withExt } from '#utils/file.mjs';
+import { QUERIES } from '#utils/queries/index.mjs';
+import { getRemark as remark, getRemarkMdx } from '#utils/remark.mjs';
+
 import { STABILITY_INDEX_URL } from './constants.mjs';
-import getConfig from '../../utils/configuration/index.mjs';
-import { withExt } from '../../utils/file.mjs';
-import { QUERIES } from '../../utils/queries/index.mjs';
-import { getRemark as remark, getRemarkMdx } from '../../utils/remark.mjs';
 
 /**
  * Determines whether a file should be parsed as MDX. A `.mdx` extension opts in

package/src/generators/ast-js/generate.mjs

@@ -6,7 +6,7 @@ import { extname } from 'node:path';
 import { parse } from 'acorn';
 import { globSync } from 'tinyglobby';
 
-import getConfig from '../../utils/configuration/index.mjs';
+import getConfig from '#utils/configuration/index.mjs';
 
 /**
  * Process a chunk of JavaScript files in a worker thread.

package/src/generators/index.mjs

@@ -22,6 +22,7 @@ export const publicGenerators = {
   'llms-txt': '@doc-kit/generator-react/llms-txt',
   sitemap: '@doc-kit/generator-react/sitemap',
   html: '@doc-kit/generator-react/html',
+  'section-pages': '@doc-kit/generator-react/section-pages',
 };
 
 // These ones are special since they don't produce standard output,

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

@@ -4,9 +4,9 @@ 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 { UNIST } from '../../utils/queries/index.mjs';
+import getConfig from '#utils/configuration/index.mjs';
+import { writeFile } from '#utils/file.mjs';
+import { UNIST } from '#utils/queries/index.mjs';
 
 /**
  * Generates the simplified JSON version of the API docs

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/generate.mjs

@@ -1,8 +1,9 @@
 'use strict';
 
+import getConfig from '#utils/configuration/index.mjs';
+import { loadFromURL } from '#utils/loaders.mjs';
+
 import { parseApiDoc } from './utils/parse.mjs';
-import getConfig from '../../utils/configuration/index.mjs';
-import { loadFromURL } from '../../utils/loaders.mjs';
 
 /**
  * Process a chunk of API doc files in a worker thread.

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

@@ -120,6 +120,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 +153,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/metadata/utils/parse.mjs

@@ -9,6 +9,15 @@ import { remove } from 'unist-util-remove';
 import { selectAll } from 'unist-util-select';
 import { SKIP, visit } from 'unist-util-visit';
 
+import {
+  DEPRECATION_HEADING_REGEX,
+  IGNORE_STABILITY_STEMS,
+} from '#generators/metadata/constants.mjs';
+import { UNIST } from '#utils/queries/index.mjs';
+import { getRemark as remark } from '#utils/remark.mjs';
+import { relative } from '#utils/url.mjs';
+
+import { resolveTypeAnnotations } from './resolveTypes.mjs';
 import createNodeSlugger from './slugger.mjs';
 import { transformNodeToHeading } from './transformers.mjs';
 import {
@@ -18,14 +27,6 @@ import {
   visitTextWithUnixManualNode,
   visitYAML,
 } from './visitors.mjs';
-import { UNIST } from '../../../utils/queries/index.mjs';
-import { getRemark as remark } from '../../../utils/remark.mjs';
-import { relative } from '../../../utils/url.mjs';
-import {
-  DEPRECATION_HEADING_REGEX,
-  IGNORE_STABILITY_STEMS,
-} from '../constants.mjs';
-import { resolveTypeAnnotations } from './resolveTypes.mjs';
 
 /**
  * This generator generates a flattened list of metadata entries from a API doc
@@ -87,7 +88,7 @@ export const parseApiDoc = ({ path, tree, mdx = false }, typeMap) => {
   // Handles the normalisation URLs that reference to API doc files with .md extension
   visit(tree, UNIST.isMarkdownUrl, node => visitMarkdownLink(node));
 
-  // If the document has no headings but it has content, we add a fake heading to the top
+  // If the document has no headings but it has content, we add a fake heading to the top, it will not be rendered
   if (headingNodes.length === 0 && tree.children.length > 0) {
     tree.children.unshift(createTree('heading', { depth: 1 }, []));
   }

package/src/generators/metadata/utils/resolveTypes.mjs

@@ -1,9 +1,10 @@
 import { parseSync } from '@swc/wasm';
 import { visit } from 'unist-util-visit';
 
+import logger from '#logger/index.mjs';
+import { walk } from '#utils/swc.mjs';
+
 import { lookupTypeName, resolveTypeReference } from './transformers.mjs';
-import logger from '../../../logger/index.mjs';
-import { walk } from '../../../utils/swc.mjs';
 
 // `null` is a keyword kind in SWC, unlike most parsers which treat it as a literal type
 const KEYWORDS = new Set([

package/src/generators/metadata/utils/slugger.mjs

@@ -2,7 +2,7 @@
 
 import GitHubSlugger, { slug as defaultSlugFn } from 'github-slugger';
 
-import { DOC_API_SLUGS_REPLACEMENTS } from '../constants.mjs';
+import { DOC_API_SLUGS_REPLACEMENTS } from '#generators/metadata/constants.mjs';
 
 /**
  * Creates a modified version of the GitHub Slugger

package/src/generators/metadata/utils/transformers.mjs

@@ -2,11 +2,12 @@ import {
   DOC_MAN_BASE_URL,
   DOC_API_HEADING_TYPES,
   MODULE_QUALIFIED_NAME,
-} from '../constants.mjs';
+} from '#generators/metadata/constants.mjs';
+import BUILTIN_TYPE_MAP from '#generators/metadata/maps/builtin.json' with { type: 'json' };
+import MDN_TYPE_MAP from '#generators/metadata/maps/mdn.json' with { type: 'json' };
+import { transformNodesToString } from '#utils/unist.mjs';
+
 import { slug } from './slugger.mjs';
-import { transformNodesToString } from '../../../utils/unist.mjs';
-import BUILTIN_TYPE_MAP from '../maps/builtin.json' with { type: 'json' };
-import MDN_TYPE_MAP from '../maps/mdn.json' with { type: 'json' };
 
 /**
  * @param {string} text The inner text

package/src/generators/metadata/utils/visitors.mjs

@@ -2,11 +2,12 @@
 
 import { SKIP } from 'unist-util-visit';
 
+import { QUERIES } from '#utils/queries/index.mjs';
+import { getRemark as remark } from '#utils/remark.mjs';
+import { transformNodesToString } from '#utils/unist.mjs';
+
 import { transformUnixManualToLink } from './transformers.mjs';
 import { extractYamlContent, parseYAMLIntoMetadata } from './yaml.mjs';
-import { QUERIES } from '../../../utils/queries/index.mjs';
-import { getRemark as remark } from '../../../utils/remark.mjs';
-import { transformNodesToString } from '../../../utils/unist.mjs';
 
 /**
  * Updates a Markdown link into a HTML link for API docs

package/src/generators/metadata/utils/yaml.mjs

@@ -2,7 +2,7 @@
 
 import yaml from 'yaml';
 
-import { QUERIES } from '../../../utils/queries/index.mjs';
+import { QUERIES } from '#utils/queries/index.mjs';
 
 /**
  * Extracts raw YAML content from a node

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/transports/console.mjs

@@ -2,8 +2,8 @@
 
 import { styleText } from 'node:util';
 
-import { prettifyLevel } from '../utils/colors.mjs';
-import { prettifyTimestamp } from '../utils/time.mjs';
+import { prettifyLevel } from '#logger/utils/colors.mjs';
+import { prettifyTimestamp } from '#logger/utils/time.mjs';
 
 /**
  * Logs a formatted message to stdout for human-friendly CLI output.

package/src/logger/transports/github.mjs

@@ -2,9 +2,9 @@
 
 import { debug, notice, warning, error } from '@actions/core';
 
-import { LogLevel } from '../constants.mjs';
-import { prettifyLevel } from '../utils/colors.mjs';
-import { prettifyTimestamp } from '../utils/time.mjs';
+import { LogLevel } from '#logger/constants.mjs';
+import { prettifyLevel } from '#logger/utils/colors.mjs';
+import { prettifyTimestamp } from '#logger/utils/time.mjs';
 
 const actions = {
   [LogLevel.debug]: debug,

package/src/logger/utils/colors.mjs

@@ -2,7 +2,7 @@
 
 import { styleText } from 'node:util';
 
-import { levelTags, levelToColorMap } from '../constants.mjs';
+import { levelTags, levelToColorMap } from '#logger/constants.mjs';
 
 /**
  * Returns a styled, uppercase log level tag for CLI output with color mapping

package/src/parsers/markdown.mjs

@@ -2,7 +2,7 @@
 
 import { coerce } from 'semver';
 
-import { loadFromURL } from '../utils/loaders.mjs';
+import { loadFromURL } from '#utils/loaders.mjs';
 
 // A ReGeX for retrieving Node.js version headers from the CHANGELOG.md
 const NODE_VERSIONS_REGEX = /\* \[Node\.js ([0-9.]+)\]\S+ (.*)\r?\n/g;
@@ -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,5 +1,5 @@
-import { loadGenerator } from '../generators/loader.mjs';
-import { setConfig } from '../utils/configuration/index.mjs';
+import { loadGenerator } from '#generators/loader.mjs';
+import { setConfig } from '#utils/configuration/index.mjs';
 
 /**
  * Processes a chunk of items using the specified generator's processChunk method.

package/src/threading/index.mjs

@@ -1,6 +1,6 @@
 import Piscina from 'piscina';
 
-import logger from '../logger/index.mjs';
+import logger from '#logger/index.mjs';
 
 const poolLogger = logger.child('WorkerPool');
 

package/src/threading/parallel.mjs

@@ -1,6 +1,6 @@
 'use strict';
 
-import logger from '../logger/index.mjs';
+import logger from '#logger/index.mjs';
 
 const parallelLogger = logger.child('parallel');
 

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

@@ -11,12 +11,14 @@ import { coerce } from 'semver';
 import {
   loadGenerators,
   resolveGeneratorSpecifier,
-} from '../../generators/loader.mjs';
-import logger from '../../logger/index.mjs';
-import { parseChangelog, parseIndex } from '../../parsers/markdown.mjs';
-import { enforceArray } from '../array.mjs';
-import { leftHandAssign } from '../generators.mjs';
-import { deepMerge } from '../misc.mjs';
+} from '#generators/loader.mjs';
+import logger from '#logger/index.mjs';
+import { parseChangelog, parseIndex } from '#parsers/markdown.mjs';
+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/configuration/types.d.ts

@@ -1,5 +1,5 @@
 import type { SemVer } from 'semver';
-import type { ReleaseEntry } from '../../parsers/types';
+import type { ReleaseEntry } from '#parsers/types';
 
 export type Configuration = {
   global: GlobalConfiguration;

package/src/utils/generators.mjs

@@ -2,6 +2,36 @@
 
 import { coerce, major } from 'semver';
 
+import { transformNodeToString } from './unist.mjs';
+
+/**
+ * Retrieves the description of a given API doc entry. It first checks whether
+ * the entry has a llm_description property. If not, it extracts the first
+ * paragraph from the entry's content.
+ *
+ * @param {import('../generators/metadata/types').MetadataEntry} entry
+ * @returns {string}
+ */
+export const getEntryDescription = entry => {
+  if (entry.llm_description) {
+    return entry.llm_description.trim();
+  }
+
+  const descriptionNode = entry.content.children.find(
+    child => child.type === 'paragraph'
+  );
+
+  if (!descriptionNode) {
+    return '';
+  }
+
+  return (
+    transformNodeToString(descriptionNode)
+      // Remove newlines and extra spaces
+      .replace(/[\r\n]+/g, '')
+  );
+};
+
 /**
  * Groups all the API metadata nodes by module (`api` property) so that we can process each different file
  * based on the module it belongs to.

package/src/utils/inline.mjs

@@ -0,0 +1,82 @@
+'use strict';
+
+import rehypeStringify from 'rehype-stringify';
+import remarkParse from 'remark-parse';
+import remarkRehype from 'remark-rehype';
+import { unified } from 'unified';
+import { u as createTree } from 'unist-builder';
+import { SKIP, visit } from 'unist-util-visit';
+
+import { lazy } from './misc.mjs';
+
+/**
+ * Renders a `root` as just its children, since content placed directly on one
+ * is otherwise rendered with a line break between each node, which surfaces as
+ * stray whitespace.
+ *
+ * @param {import('mdast-util-to-hast').State} state
+ * @param {import('unist').Parent} node
+ */
+const inlineRoot = (state, node) => ({
+  type: 'root',
+  children: state.all(node),
+});
+
+/**
+ * Retrieves an instance of Remark configured to parse plain markdown, without
+ * the extensions that only apply to whole documents.
+ */
+const getInlineParser = lazy(() => unified().use(remarkParse));
+
+/**
+ * Retrieves an instance of Remark configured to render inline nodes as an HTML
+ * string. Raw HTML is dropped rather than passed through, since the result is
+ * inserted into the page as-is.
+ */
+const getInlineRenderer = lazy(() =>
+  unified()
+    .use(remarkRehype, { handlers: { root: inlineRoot } })
+    .use(rehypeStringify)
+);
+
+/**
+ * Parses a single line of markdown (a change description, a summary, ...) into
+ * the inline nodes it is made of.
+ *
+ * @param {string} markdown - The markdown to parse.
+ * @param {boolean} [dropLinks] - Replace links with their text? Anchors cannot
+ * nest, so content rendered inside a link must not contain one.
+ * @returns {Array<import('mdast').PhrasingContent>} The parsed nodes.
+ */
+export const parseInline = (markdown, dropLinks = false) => {
+  const tree = getInlineParser().parse(markdown);
+
+  if (dropLinks) {
+    visit(tree, 'link', (node, index, parent) => {
+      parent.children.splice(index, 1, ...node.children);
+
+      return [SKIP, index];
+    });
+  }
+
+  const [first] = tree.children;
+
+  // A single line of prose parses into one paragraph, which is dropped so the
+  // nodes can be rendered inline
+  return tree.children.length === 1 && first.type === 'paragraph'
+    ? first.children
+    : tree.children;
+};
+
+/**
+ * Renders inline nodes as an HTML string, for the places that hand rendered
+ * markup to a component through a data channel rather than as an AST.
+ *
+ * @param {Array<import('mdast').PhrasingContent>} nodes - The nodes to render.
+ * @returns {string} The rendered HTML.
+ */
+export const renderAsHTML = nodes => {
+  const renderer = getInlineRenderer();
+
+  return renderer.stringify(renderer.runSync(createTree('root', nodes)));
+};

package/src/utils/queries/index.mjs

@@ -1,7 +1,8 @@
 'use strict';
 
-import { transformNodesToString } from '../unist.mjs';
-import { isTypedList } from './utils.mjs';
+import { transformNodesToString } from '#utils/unist.mjs';
+
+import { isTypedListItem, isTypedList } from './utils.mjs';
 
 // This defines the actual REGEX Queries
 export const QUERIES = {
@@ -71,6 +72,12 @@ export const UNIST = {
    */
   isLooselyTypedList: list => Boolean(isTypedList(list)),
 
+  /**
+   * @param {import('@types/mdast').ListItem} item
+   * @returns {boolean}
+   */
+  isTypedListItem,
+
   /**
    * @param {import('@types/mdast').List} list
    * @returns {boolean}

package/src/utils/queries/utils.mjs

@@ -2,20 +2,17 @@ import { VALID_JAVASCRIPT_PROPERTY } from './constants.mjs';
 import { QUERIES } from './index.mjs';
 
 /**
- * @param {import('@types/mdast').List} list
+ * Inspects the first phrasing node of a paragraph and returns how confidently
+ * it looks like the start of a typed parameter.
+ *
+ * @param {import('@types/mdast').PhrasingContent | undefined} firstNode
  * @returns {0 | 1 | 2} confidence
  *
- * 0: This is not a typed list
- * 1: This is a loosely typed list
- * 2: This is a strongly typed list
+ * 0: Not a typed parameter
+ * 1: Loosely typed (inlineCode + valid property name)
+ * 2: Strongly typed (typed list starter or direct type annotation)
  */
-export const isTypedList = list => {
-  if (!list || list.type !== 'list') {
-    return 0;
-  }
-
-  const firstNode = list.children?.[0]?.children?.[0]?.children[0];
-
+const getTypedConfidence = firstNode => {
   if (!firstNode) {
     return 0;
   }
@@ -43,3 +40,30 @@ export const isTypedList = list => {
 
   return 0;
 };
+
+/**
+ * Checks whether a single list item looks like a typed parameter — i.e. it
+ * starts with a property name (`inlineCode`), a Returns/Extends/Type prefix,
+ * or a direct type annotation.
+ *
+ * @param {import('@types/mdast').ListItem} item
+ * @returns {boolean}
+ */
+export const isTypedListItem = item =>
+  Boolean(getTypedConfidence(item?.children?.[0]?.children?.[0]));
+
+/**
+ * @param {import('@types/mdast').List} list
+ * @returns {0 | 1 | 2} confidence
+ *
+ * 0: This is not a typed list
+ * 1: This is a loosely typed list
+ * 2: This is a strongly typed list
+ */
+export const isTypedList = list => {
+  if (!list || list.type !== 'list') {
+    return 0;
+  }
+
+  return getTypedConfidence(list.children?.[0]?.children?.[0]?.children?.[0]);
+};

package/src/utils/remark-shiki.mjs

@@ -0,0 +1,29 @@
+'use strict';
+
+import rehypeStringify from 'rehype-stringify';
+import remarkParse from 'remark-parse';
+import remarkRehype from 'remark-rehype';
+import { unified } from 'unified';
+
+import syntaxHighlighter from './highlighter.mjs';
+import { lazy } from './misc.mjs';
+import { rehypeOptions } from './remark.mjs';
+
+/**
+ * Retrieves an instance of Remark configured to output stringified HTML code
+ * including parsing Code Boxes with syntax highlighting.
+ *
+ * This lives apart from `./remark.mjs` because importing it loads Shiki (every
+ * grammar plus the regex engine, ~250MB per process). Only the generators that
+ * highlight code — `legacy-html` here — should pay for that.
+ */
+export const getRemarkRehypeWithShiki = lazy(() =>
+  unified()
+    .use(remarkParse)
+    // legacy-html gets the minimal (unhighlighted) type rendering
+    .use(remarkRehype, rehypeOptions)
+    // This is a custom ad-hoc within the Shiki Rehype plugin, used to highlight code
+    // and transform them into HAST nodes
+    .use(syntaxHighlighter)
+    .use(rehypeStringify, { allowDangerousHtml: true })
+);

package/src/utils/remark.mjs

@@ -8,23 +8,51 @@ import remarkRehype from 'remark-rehype';
 import remarkStringify from 'remark-stringify';
 import { unified } from 'unified';
 
-import syntaxHighlighter from './highlighter.mjs';
 import { lazy } from './misc.mjs';
 import { typeAnnotationToHast } from './type-annotations/hast.mjs';
 import remarkTypeAnnotations from './type-annotations/remark.mjs';
 
-// MDX node types that may appear in trees parsed by `getRemarkMdx`; the
-// rehype pipelines pass them through untouched.
-const passThrough = [
-  'element',
-  'mdxJsxTextElement',
-  'mdxJsxFlowElement',
-  'mdxJsxAttribute',
-  'mdxJsxAttributeValueExpression',
-  'mdxFlowExpression',
-  'mdxTextExpression',
-  'mdxjsEsm',
-];
+// Nothing in this module loads Shiki: the `ast` and `metadata` stages (and
+// every worker that runs them) import it, and none of them highlight code.
+// The highlighting pipeline lives in `./remark-shiki.mjs`.
+
+/**
+ * Renders an MDX JSX element as just its children, so the surrounding prose
+ * still renders in HTML-string output.
+ *
+ * @param {import('mdast-util-to-hast').State} state
+ * @param {import('unist').Parent} node
+ */
+const mdxElementToChildren = (state, node) => state.all(node);
+
+/**
+ * Drops a node from HTML-string output.
+ */
+const dropNode = () => undefined;
+
+/**
+ * The `remark-rehype` options shared by the HTML-string pipelines.
+ *
+ * Existing HTML nodes pass through untouched (they were created during the
+ * rehype process), and dangerous HTML is allowed since the Markdown sources
+ * are trusted. The MDX node types cannot be rendered to an HTML string (that
+ * is the React generators' job): JSX elements degrade to their children so the
+ * surrounding prose still renders, and expressions/ESM are dropped.
+ *
+ * @type {import('remark-rehype').Options}
+ */
+export const rehypeOptions = {
+  allowDangerousHtml: true,
+  passThrough: ['element'],
+  handlers: {
+    typeAnnotation: typeAnnotationToHast,
+    mdxJsxTextElement: mdxElementToChildren,
+    mdxJsxFlowElement: mdxElementToChildren,
+    mdxFlowExpression: dropNode,
+    mdxTextExpression: dropNode,
+    mdxjsEsm: dropNode,
+  },
+};
 
 /**
  * Retrieves an instance of Remark configured to parse GFM (GitHub Flavored Markdown)
@@ -57,41 +85,6 @@ export const getRemarkMdx = lazy(() =>
 export const getRemarkRehype = lazy(() =>
   unified()
     .use(remarkParse)
-    // We make Rehype ignore existing HTML nodes (just the node itself, not its children)
-    // as these are nodes we manually created during the rehype process
-    // We also allow dangerous HTML to be passed through, since we have HTML within our Markdown
-    // and we trust the sources of the Markdown files
-    .use(remarkRehype, {
-      allowDangerousHtml: true,
-      passThrough,
-      handlers: { typeAnnotation: typeAnnotationToHast },
-    })
-    // We allow dangerous HTML to be passed through, since we have HTML within our Markdown
-    // and we trust the sources of the Markdown files
-    .use(rehypeStringify, { allowDangerousHtml: true })
-);
-
-/**
- * Retrieves an instance of Remark configured to output stringified HTML code
- * including parsing Code Boxes with syntax highlighting
- */
-export const getRemarkRehypeWithShiki = lazy(() =>
-  unified()
-    .use(remarkParse)
-    // We make Rehype ignore existing HTML nodes (just the node itself, not its children)
-    // as these are nodes we manually created during the rehype process
-    // We also allow dangerous HTML to be passed through, since we have HTML within our Markdown
-    // and we trust the sources of the Markdown files
-    .use(remarkRehype, {
-      allowDangerousHtml: true,
-      passThrough,
-      // legacy-html gets the minimal (unhighlighted) type rendering
-      handlers: { typeAnnotation: typeAnnotationToHast },
-    })
-    // This is a custom ad-hoc within the Shiki Rehype plugin, used to highlight code
-    // and transform them into HAST nodes
-    .use(syntaxHighlighter)
-    // We allow dangerous HTML to be passed through, since we have HTML within our Markdown
-    // and we trust the sources of the Markdown files
+    .use(remarkRehype, rehypeOptions)
     .use(rehypeStringify, { allowDangerousHtml: true })
 );

package/src/utils/signature/parseList.mjs

@@ -1,12 +1,13 @@
+import { leftHandAssign } from '#utils/generators.mjs';
+import { QUERIES, UNIST } from '#utils/queries/index.mjs';
+import { transformNodesToString } from '#utils/unist.mjs';
+
 import {
   DEFAULT_EXPRESSION,
   LEADING_HYPHEN,
   NAME_EXPRESSION,
 } from './constants.mjs';
 import parseSignature from './parseSignature.mjs';
-import { leftHandAssign } from '../generators.mjs';
-import { QUERIES, UNIST } from '../queries/index.mjs';
-import { transformNodesToString } from '../unist.mjs';
 
 /**
  * Extracts and removes a specific pattern from a text string while storing the result in a key of the `current` object.

package/src/utils/type-annotations/hast.mjs

@@ -1,9 +1,5 @@
 'use strict';
 
-import { highlighter } from '../highlighter.mjs';
-
-const [lightTheme, darkTheme] = highlighter.shiki.getLoadedThemes();
-
 /**
  * Slices a type's text by its resolved link ranges into hast children —
  * plain text segments interleaved with `<a class="type-link">` anchors.
@@ -59,57 +55,3 @@ export const typeAnnotationToHast = (state, node) => {
 
   return state.applyData(node, result);
 };
-
-/**
- * Syntax-highlighted mdast→hast handler for `typeAnnotation` nodes, used by
- * the web (JSX) pipeline. The whole type is highlighted as one inline
- * fragment, and each resolved identifier's exact character range is wrapped
- * in an `<a>` via Shiki decorations. Values that are not TypeScript (display
- * names such as `HTTP/2 Headers Object`) are highlighted as plain text, so
- * their prose is not coloured as operators and numeric literals.
- *
- * Falls back to the minimal handler when the type failed to parse or nothing
- * resolved (no point paying for highlighting then).
- *
- * @param {import('mdast-util-to-hast').State} state
- * @param {import('mdast').Node} node
- * @returns {import('hast').Element}
- */
-export const typeAnnotationToHighlightedHast = (state, node) => {
-  const links = node.data?.links ?? [];
-
-  if (node.data?.parseError || links.length === 0) {
-    return typeAnnotationToHast(state, node);
-  }
-
-  const root = highlighter.shiki.codeToHast(node.value, {
-    lang: node.data?.typescript ? 'typescript' : 'text',
-    themes: { light: lightTheme, dark: darkTheme },
-    decorations: links.map(({ start, end, href }) => ({
-      start,
-      end,
-      tagName: 'a',
-      properties: { href, class: 'type-link' },
-      alwaysWrap: true,
-    })),
-  });
-
-  // codeToHast wraps the highlighted line in <pre><code>; re-shape that into
-  // a single inline <code> element ("only the outermost type opens/closes
-  // the code fragment")
-  const [preElement] = root.children;
-  const [codeElement] = preElement.children;
-
-  const result = {
-    type: 'element',
-    tagName: 'code',
-    properties: {
-      class: `${preElement.properties.class} type`,
-    },
-    children: codeElement.children,
-  };
-
-  state.patch(node, result);
-
-  return state.applyData(node, result);
-};

package/src/utils/type-annotations/highlighted.mjs

@@ -0,0 +1,64 @@
+'use strict';
+
+import { highlighter } from '#utils/highlighter.mjs';
+
+import { typeAnnotationToHast } from './hast.mjs';
+
+// Kept apart from `./hast.mjs` on purpose: importing this module loads Shiki
+// (every grammar plus the regex engine), which only the pipelines that
+// highlight should pay for. The `ast` and `metadata` stages never do.
+const [lightTheme, darkTheme] = highlighter.shiki.getLoadedThemes();
+
+/**
+ * Syntax-highlighted mdast→hast handler for `typeAnnotation` nodes, used by
+ * the web (JSX) pipeline. The whole type is highlighted as one inline
+ * fragment, and each resolved identifier's exact character range is wrapped
+ * in an `<a>` via Shiki decorations. Values that are not TypeScript (display
+ * names such as `HTTP/2 Headers Object`) are highlighted as plain text, so
+ * their prose is not coloured as operators and numeric literals.
+ *
+ * Falls back to the minimal handler when the type failed to parse or nothing
+ * resolved (no point paying for highlighting then).
+ *
+ * @param {import('mdast-util-to-hast').State} state
+ * @param {import('mdast').Node} node
+ * @returns {import('hast').Element}
+ */
+export const typeAnnotationToHighlightedHast = (state, node) => {
+  const links = node.data?.links ?? [];
+
+  if (node.data?.parseError || links.length === 0) {
+    return typeAnnotationToHast(state, node);
+  }
+
+  const root = highlighter.shiki.codeToHast(node.value, {
+    lang: node.data?.typescript ? 'typescript' : 'text',
+    themes: { light: lightTheme, dark: darkTheme },
+    decorations: links.map(({ start, end, href }) => ({
+      start,
+      end,
+      tagName: 'a',
+      properties: { href, class: 'type-link' },
+      alwaysWrap: true,
+    })),
+  });
+
+  // codeToHast wraps the highlighted line in <pre><code>; re-shape that into
+  // a single inline <code> element ("only the outermost type opens/closes
+  // the code fragment")
+  const [preElement] = root.children;
+  const [codeElement] = preElement.children;
+
+  const result = {
+    type: 'element',
+    tagName: 'code',
+    properties: {
+      class: `${preElement.properties.class} type`,
+    },
+    children: codeElement.children,
+  };
+
+  state.patch(node, result);
+
+  return state.applyData(node, result);
+};