@doc-kit/core 1.0.1 → 1.2.0

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-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,13 +8,13 @@ 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';
 
-// Nodes the rehype pipelines pass through untouched.
-const passThrough = ['element'];
+// 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
@@ -30,15 +30,28 @@ const mdxElementToChildren = (state, node) => state.all(node);
  */
 const dropNode = () => undefined;
 
-// The HTML-string pipelines cannot render MDX nodes (rendering those is the
-// React generators' job): JSX elements degrade to their children so the
-// surrounding prose still renders, and expressions/ESM are dropped.
-const mdxToHastHandlers = {
-  mdxJsxTextElement: mdxElementToChildren,
-  mdxJsxFlowElement: mdxElementToChildren,
-  mdxFlowExpression: dropNode,
-  mdxTextExpression: dropNode,
-  mdxjsEsm: dropNode,
+/**
+ * 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,
+  },
 };
 
 /**
@@ -63,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)
 );
 
 /**
@@ -72,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, ...mdxToHastHandlers },
-    })
-    // 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, ...mdxToHastHandlers },
-    })
-    // 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/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;
+};

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

@@ -1,9 +1,5 @@
 'use strict';
 
-import { highlighter } from '#utils/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);
+};