@doc-kit/core 1.1.0 → 1.2.1

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/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",
@@ -472,6 +475,7 @@
   "magnetometer": "https://developer.mozilla.org/docs/Web/API/Magnetometer",
   "managedmediasource": "https://developer.mozilla.org/docs/Web/API/ManagedMediaSource",
   "managedsourcebuffer": "https://developer.mozilla.org/docs/Web/API/ManagedSourceBuffer",
+  "mathmlanchorelement": "https://developer.mozilla.org/docs/Web/API/MathMLAnchorElement",
   "mathmlelement": "https://developer.mozilla.org/docs/Web/API/MathMLElement",
   "mediacapabilities": "https://developer.mozilla.org/docs/Web/API/MediaCapabilities",
   "mediadeviceinfo": "https://developer.mozilla.org/docs/Web/API/MediaDeviceInfo",
@@ -589,7 +593,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 +642,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 +679,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 +755,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 +952,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 +1021,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;
 }
 
 /**

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

@@ -72,7 +72,7 @@ export const resolveTypeReference = (name, typeMap) => {
   // Transform Node.js types like 'vm.Something'.
   if (MODULE_QUALIFIED_NAME.test(name)) {
     const [mod, ...pieces] = name.split('.');
-    const isClass = pieces.at(-1).match(/^[A-Z][a-z]/);
+    const isClass = pieces.at(-1).match(/^[A-Z](?=.*[a-z])/);
 
     return `${mod}.html#${isClass ? 'class-' : ''}${slug(name)}`;
   }

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/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/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;
+};

package/src/utils/overloads.mjs

@@ -0,0 +1,54 @@
+'use strict';
+
+// Heading types that document a callable and therefore may appear several times
+// in a row as overloaded signatures of the same function.
+const OVERLOADABLE_TYPES = new Set(['method', 'ctor', 'classMethod']);
+
+/**
+ * Two headings document the same function (i.e. are overloads of one another)
+ * when they sit at the same depth and share the same resolved name and type.
+ *
+ * @param {import('../generators/metadata/types').HeadingNode} a
+ * @param {import('../generators/metadata/types').HeadingNode} b
+ */
+const isSameFunction = (a, b) =>
+  a.depth === b.depth &&
+  a.data.type === b.data.type &&
+  a.data.name === b.data.name;
+
+/**
+ * Flags overloaded function headings so consumers can present a single entry
+ * per function.
+ *
+ * Node.js documents each overload of a function as its own heading (e.g. the
+ * five `new Buffer(...)` signatures). This marks the 2nd..nth heading of each
+ * such run with `isOverload`, and with `overloadOf` pointing at the slug of
+ * the run's first heading. The first (most stable) heading is left as-is.
+ *
+ * @param {Array<import('../generators/metadata/types').MetadataEntry>} entries - Entries, in document order.
+ * @returns {Array<import('../generators/metadata/types').MetadataEntry>} The same entries (mutated).
+ */
+export const annotateOverloads = entries => {
+  for (let i = 0; i < entries.length; i++) {
+    const { heading } = entries[i];
+
+    if (!OVERLOADABLE_TYPES.has(heading.data.type)) {
+      continue;
+    }
+
+    // Flag each following heading that overloads the same function.
+    let end = i + 1;
+    while (
+      end < entries.length &&
+      isSameFunction(entries[end].heading, heading)
+    ) {
+      entries[end].heading.data.isOverload = true;
+      entries[end].heading.data.overloadOf = heading.data.slug;
+      end++;
+    }
+
+    i = end - 1;
+  }
+
+  return entries;
+};

package/src/utils/queries/index.mjs

@@ -4,6 +4,8 @@ import { transformNodesToString } from '#utils/unist.mjs';
 
 import { isTypedListItem, isTypedList } from './utils.mjs';
 
+export { splitTypedItems } from './utils.mjs';
+
 // This defines the actual REGEX Queries
 export const QUERIES = {
   // Fixes the references to Markdown pages into the API documentation

package/src/utils/queries/utils.mjs

@@ -67,3 +67,18 @@ export const isTypedList = list => {
 
   return getTypedConfidence(list.children?.[0]?.children?.[0]?.children?.[0]);
 };
+
+/**
+ * Splits a typed list's items into the leading typed ones and the rest:
+ * prose bullets that happen to share the list in the source markdown.
+ *
+ * @param {import('@types/mdast').List} list
+ * @returns {{ typed: Array<import('@types/mdast').ListItem>, rest: Array<import('@types/mdast').ListItem> }}
+ */
+export const splitTypedItems = ({ children }) => {
+  const end = children.findIndex(item => !isTypedListItem(item));
+
+  return end === -1
+    ? { typed: children, rest: [] }
+    : { typed: children.slice(0, end), rest: children.slice(end) };
+};

package/src/utils/remark.mjs

@@ -76,7 +76,7 @@ export const getRemark = lazy(() =>
  * `{` for type annotations that MDX would otherwise try to parse.
  */
 export const getRemarkMdx = lazy(() =>
-  unified().use(remarkParse).use(remarkMdx).use(remarkGfm)
+  unified().use(remarkParse).use(remarkMdx).use(remarkGfm).use(remarkStringify)
 );
 
 /**

package/src/utils/signature/constants.mjs

@@ -4,6 +4,9 @@ export const NAME_EXPRESSION = /^['`"]?([^'`": {]+)['`"]?\s*:?\s*/;
 // Checks if there's a leading hyphen
 export const LEADING_HYPHEN = /^-\s*/;
 
+// The separators between a parameter's type and its description
+export const TRIMMABLE_PADDING_REGEX = /^[\s:-]+/;
+
 // Grabs the default value if present
 export const DEFAULT_EXPRESSION = /\s*\*\*Default:\*\*\s*([^]+)$/i;
 

package/src/utils/signature/extractListItem.mjs

@@ -0,0 +1,140 @@
+'use strict';
+
+import { QUERIES, UNIST } from '#utils/queries/index.mjs';
+import { transformNodesToString } from '#utils/unist.mjs';
+
+import { DEFAULT_EXPRESSION, TRIMMABLE_PADDING_REGEX } from './constants.mjs';
+
+// The text of the `**Default:**` marker introducing a default value
+const DEFAULT_MARKER = /^default:$/i;
+
+/**
+ * A typed list item taken apart into its parts, none of them stringified, so
+ * each consumer can render the description its own way.
+ *
+ * @typedef {object} ExtractedListItem
+ * @property {string | undefined} name The parameter name (the leading code span), if any
+ * @property {'Returns' | 'Extends' | 'Type' | undefined} prefix The special prefix the item starts with, if any
+ * @property {import('mdast').Node | undefined} annotation The leading `typeAnnotation` node, if any
+ * @property {Array<import('mdast').PhrasingContent>} text The rest of the first paragraph: the description,
+ * with leading separators trimmed and any `**Default:**` marker still in place
+ * @property {Array<import('mdast').BlockContent>} blocks The item's further block content, excluding its nested typed list
+ * @property {string | undefined} default The `**Default:**` value as written (code span included), if any
+ * @property {Array<import('mdast').ListItem>} items The items of the nested typed list, if any
+ */
+
+/**
+ * Replaces the first node's text, or drops the node when nothing is left.
+ *
+ * @param {Array<import('mdast').PhrasingContent>} nodes
+ * @param {string} value The new text of the first node
+ */
+const replaceLeadingText = (nodes, value) => {
+  if (value.trim()) {
+    nodes[0] = { ...nodes[0], value };
+  } else {
+    nodes.shift();
+  }
+};
+
+/**
+ * Takes a typed list item apart: `` `name` {Type} Description. **Default:** `value` ``,
+ * or one of the `Returns:`, `Extends:` and `Type:` forms.
+ *
+ * @param {import('mdast').ListItem} item
+ * @returns {ExtractedListItem}
+ */
+export const extractListItem = item => {
+  const [paragraph, ...rest] = item.children ?? [];
+  const text = [...(paragraph?.children ?? [])];
+
+  const result = {
+    name: undefined,
+    prefix: undefined,
+    annotation: undefined,
+    text,
+    blocks: [],
+    default: undefined,
+    items: [],
+  };
+
+  const [first] = text;
+
+  if (first?.type === 'inlineCode') {
+    result.name = first.value.trimEnd();
+    text.shift();
+  } else if (first?.type === 'text') {
+    const match = first.value.match(QUERIES.typedListStarters);
+
+    if (match) {
+      result.prefix = match[1];
+      replaceLeadingText(text, first.value.slice(match[0].length));
+    }
+  }
+
+  // The whitespace between the name and the type
+  if (text[0]?.type === 'text' && !text[0].value.trim()) {
+    text.shift();
+  }
+
+  if (text[0]?.type === 'typeAnnotation') {
+    result.annotation = text.shift();
+  }
+
+  // Leading separators: `- description`, `: description`
+  if (text[0]?.type === 'text') {
+    replaceLeadingText(
+      text,
+      text[0].value.replace(TRIMMABLE_PADDING_REGEX, '')
+    );
+  }
+
+  result.default = DEFAULT_EXPRESSION.exec(transformNodesToString(text))?.[1]
+    .trim()
+    .replace(/\.$/, '');
+
+  for (const node of rest) {
+    if (result.items.length === 0 && UNIST.isLooselyTypedList(node)) {
+      result.items = node.children;
+    } else {
+      result.blocks.push(node);
+    }
+  }
+
+  return result;
+};
+
+/**
+ * Drops the `**Default:**` marker, and everything after it, from an item's
+ * description.
+ *
+ * @param {Array<import('mdast').PhrasingContent>} nodes The item's description
+ * @returns {Array<import('mdast').PhrasingContent>} The description without its default value
+ */
+export const removeDefault = nodes => {
+  const index = nodes.findIndex(
+    node =>
+      node.type === 'strong' &&
+      DEFAULT_MARKER.test(transformNodesToString(node.children).trim())
+  );
+
+  if (index === -1) {
+    return nodes;
+  }
+
+  const kept = nodes.slice(0, index);
+  const last = kept.at(-1);
+
+  // The whitespace that separated the description from its default
+  if (last?.type === 'text') {
+    const value = last.value.trimEnd();
+
+    kept.pop();
+
+    if (value) {
+      kept.push({ ...last, value });
+    }
+  }
+
+  return kept;
+};

package/src/utils/stability.mjs

@@ -0,0 +1,24 @@
+'use strict';
+
+import { slice } from 'mdast-util-slice-markdown';
+import { toString } from 'mdast-util-to-string';
+
+import { QUERIES } from './queries/index.mjs';
+
+/**
+ * The content of a stability blockquote without its `Stability: N - `
+ * prefix, as a copy of the blockquote. The prefix may have been turned into a
+ * link by the AST stage; the separator goes with it.
+ *
+ * @param {import('../generators/metadata/types').StabilityNode} node
+ * @returns {import('mdast').Blockquote | null} The copy, or `null` when nothing follows the prefix
+ */
+export const removeStabilityPrefix = node => {
+  const text = toString(node.children[0]);
+  const match = QUERIES.stabilityIndex.exec(text);
+  const start = match ? text.length - match[2].length : 0;
+
+  return slice(node, start, undefined, {
+    textHandling: { boundaries: 'preserve' },
+  }).node;
+};