@doc-kit/core 0.0.0

package/src/utils/loaders.mjs

@@ -0,0 +1,48 @@
+import { readFile } from 'node:fs/promises';
+import { extname, isAbsolute, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * Converts a value to a parsed URL object.
+ *
+ * @param {string|URL} url - The URL string or URL object to parse
+ * @returns {URL|null} The parsed URL object, or null if parsing fails
+ */
+export const toParsedURL = url => (url instanceof URL ? url : URL.parse(url));
+
+/**
+ * Loads content from a URL or file path
+ * @param {string|URL} url The URL or file path to load
+ * @returns {Promise<string>} The content as a string
+ */
+export const loadFromURL = async url => {
+  const parsedUrl = toParsedURL(url);
+
+  if (!parsedUrl || parsedUrl.protocol === 'file:') {
+    // Load from file system
+    return readFile(parsedUrl ?? url, 'utf-8');
+  } else {
+    // Load from network
+    const response = await fetch(parsedUrl);
+    return response.text();
+  }
+};
+
+/**
+ * Dynamically imports a module from a URL, using JSON import assertion if applicable.
+ *
+ * @param {string|URL} url - The URL of the module to import
+ * @returns {Promise<any>} The imported module
+ */
+export const importFromURL = async url => {
+  const useJSONAssertion = extname(String(url)) === '.json';
+
+  const parsed = toParsedURL(url);
+
+  const imported = await import(
+    parsed ?? pathToFileURL(isAbsolute(url) ? url : join(process.cwd(), url)),
+    useJSONAssertion ? { with: { type: 'json' } } : {}
+  );
+
+  return imported.default ?? imported;
+};

package/src/utils/misc.mjs

@@ -0,0 +1,72 @@
+/**
+ * Creates a lazy-initialized function that caches the result of the first invocation.
+ * @template {(...args: any[]) => any} T
+ * @param {T} fn - The function to be lazily executed
+ * @returns {T} A wrapper function that lazily executes fn and caches its result
+ */
+export const lazy = fn =>
+  (
+    c =>
+    (...args) =>
+      (c ??= fn(...args))
+  )();
+
+/**
+ * Checks if a value is a plain JavaScript object.
+ * @param {*} value - The value to check
+ * @returns {boolean} True if the value is a plain object, false otherwise
+ */
+export const isPlainObject = value => {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
+
+/**
+ * Checks if a value is an async generator/iterable.
+ * @param {unknown} obj - Value to check
+ * @returns {obj is AsyncGenerator} True if the value is an async iterable
+ */
+export const isAsyncIterable = obj =>
+  obj !== null &&
+  typeof obj === 'object' &&
+  typeof obj[Symbol.asyncIterator] === 'function';
+
+/**
+ * Returns a shallow copy of `obj` without the specified keys.
+ * @param {Record<string, any>} obj
+ * @param {string[]} keys - Keys to exclude
+ * @returns {Record<string, any>}
+ */
+export const omitKeys = (obj, keys = []) =>
+  Object.fromEntries(
+    Object.entries(obj).filter(([key]) => !keys.includes(key))
+  );
+
+/**
+ * Recursively merges plain objects from left to right.
+ * @template T
+ * @param {...T} objects - Any number of objects to merge
+ * @returns {T} A new object containing the deep merge of all provided objects
+ */
+export const deepMerge = (...objects) => {
+  return objects.reduce((result, source) => {
+    for (const [key, sourceValue] of Object.entries(source)) {
+      if (sourceValue === undefined) {
+        continue;
+      }
+
+      const targetValue = result[key];
+      result[key] = isPlainObject(sourceValue)
+        ? deepMerge(isPlainObject(targetValue) ? targetValue : {}, sourceValue)
+        : Array.isArray(sourceValue)
+          ? sourceValue.slice()
+          : sourceValue;
+    }
+
+    return result;
+  }, {});
+};

package/src/utils/queries/constants.mjs

@@ -0,0 +1,3 @@
+'use strict';
+
+export const VALID_JAVASCRIPT_PROPERTY = /^[.a-z0-9$_'-]+$/i;

package/src/utils/queries/index.mjs

@@ -0,0 +1,93 @@
+'use strict';
+
+import { transformNodesToString } from '../unist.mjs';
+import { isTypedList } from './utils.mjs';
+
+// This defines the actual REGEX Queries
+export const QUERIES = {
+  // Fixes the references to Markdown pages into the API documentation
+  markdownUrl: /^(?![+a-zA-Z]+:)([^#?]+)\.md(#.+)?$/,
+  // ReGeX for handling Stability Indexes Metadata
+  stabilityIndex: /^Stability: ([0-5](?:\.[0-3])?)(?:\s*-\s*)?(.*)$/s,
+  // ReGeX for handling the Stability Index Prefix
+  stabilityIndexPrefix: /Stability: ([0-5](?:\.[0-3])?)/,
+  // ReGeX for retrieving the inner content from a YAML block
+  yamlInnerContent: /^<!--[ ]?(?:YAML([\s\S]*?)|([ \S]*?))?[ ]?-->/,
+  // ReGeX for standard Markdown YAML frontmatter
+  standardYamlFrontmatter: /^---\r?\n([\s\S]*?)\r?\n---/,
+  // ReGeX for finding references to Unix manuals
+  unixManualPage: /\b([a-z.]+)\((\d)([a-z]?)\)/g,
+  // ReGeX for determing a typed list's non-property names
+  typedListStarters: /^(Returns|Extends|Type):?\s*/,
+};
+
+export const UNIST = {
+  /**
+   * @param {import('@types/mdast').Blockquote} blockquote
+   * @returns {boolean}
+   */
+  isStabilityNode: ({ type, children }) =>
+    type === 'blockquote' &&
+    QUERIES.stabilityIndex.test(transformNodesToString(children)),
+
+  /**
+   * @param {import('@types/mdast').Html} html
+   * @returns {boolean}
+   */
+  isYamlNode: ({ type, value }) =>
+    type === 'html' && QUERIES.yamlInnerContent.test(value),
+
+  /**
+   * @param {import('@types/mdast').Text} text
+   * @returns {boolean}
+   */
+  isTextWithUnixManual: ({ type, value }) =>
+    type === 'text' && QUERIES.unixManualPage.test(value),
+
+  /**
+   * @param {import('@types/mdast').Link} link
+   * @returns {boolean}
+   */
+  isMarkdownUrl: ({ type, url }) =>
+    type === 'link' && QUERIES.markdownUrl.test(url),
+
+  /**
+   * @param {import('@types/mdast').Heading} heading
+   * @returns {boolean}
+   */
+  isHeading: ({ type, depth }) =>
+    type === 'heading' && depth >= 1 && depth <= 5,
+
+  /**
+   * @param {import('@types/mdast').LinkReference} linkReference
+   * @returns {boolean}
+   */
+  isLinkReference: ({ type, identifier }) =>
+    type === 'linkReference' && !!identifier,
+
+  /**
+   * @param {import('@types/mdast').List} list
+   * @returns {boolean}
+   */
+  isLooselyTypedList: list => Boolean(isTypedList(list)),
+
+  /**
+   * @param {import('@types/mdast').List} list
+   * @returns {boolean}
+   */
+  isStronglyTypedList: list => {
+    const confidence = isTypedList(list);
+
+    if (confidence === 1) {
+      // This is a loosely typed list, but we can still check if it is strongly typed.
+      const [, secondNode, thirdNode] =
+        list.children?.[0]?.children?.[0]?.children ?? [];
+
+      return (
+        secondNode?.value?.trim() === '' && thirdNode?.type === 'typeAnnotation'
+      );
+    }
+
+    return Boolean(confidence);
+  },
+};

package/src/utils/queries/utils.mjs

@@ -0,0 +1,45 @@
+import { VALID_JAVASCRIPT_PROPERTY } from './constants.mjs';
+import { QUERIES } from './index.mjs';
+
+/**
+ * @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;
+  }
+
+  const firstNode = list.children?.[0]?.children?.[0]?.children[0];
+
+  if (!firstNode) {
+    return 0;
+  }
+
+  const value = firstNode?.value?.trimStart();
+
+  // Typed list starters (strong signal)
+  if (value && QUERIES.typedListStarters.test(value)) {
+    return 2;
+  }
+
+  // Direct type annotation: {Type}
+  if (firstNode.type === 'typeAnnotation') {
+    return 2;
+  }
+
+  // inlineCode + space (weaker signal)
+  if (
+    firstNode.type === 'inlineCode' &&
+    value &&
+    VALID_JAVASCRIPT_PROPERTY.test(value)
+  ) {
+    return 1;
+  }
+
+  return 0;
+};

package/src/utils/remark.mjs

@@ -0,0 +1,97 @@
+'use strict';
+
+import rehypeStringify from 'rehype-stringify';
+import remarkGfm from 'remark-gfm';
+import remarkMdx from 'remark-mdx';
+import remarkParse from 'remark-parse';
+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',
+];
+
+/**
+ * Retrieves an instance of Remark configured to parse GFM (GitHub Flavored Markdown)
+ * plus `{...}` type annotations (see `./type-annotations`), which only exist
+ * in non-MDX files — the MDX pipeline below never registers them.
+ */
+export const getRemark = lazy(() =>
+  unified()
+    .use(remarkParse)
+    .use(remarkTypeAnnotations)
+    .use(remarkGfm)
+    .use(remarkStringify)
+);
+
+/**
+ * Retrieves an instance of Remark configured to parse MDX (JSX-in-Markdown).
+ *
+ * Unlike {@link getRemark}, this understands `<Component />` and `{expression}`
+ * syntax as real JSX/expression nodes. It is only used for `.mdx` (or
+ * explicitly opted-in) files, since Node.js core `.md` files use bare `<` and
+ * `{` for type annotations that MDX would otherwise try to parse.
+ */
+export const getRemarkMdx = lazy(() =>
+  unified().use(remarkParse).use(remarkMdx).use(remarkGfm)
+);
+
+/**
+ * Retrieves an instance of Remark configured to output stringified HTML code
+ */
+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(rehypeStringify, { allowDangerousHtml: true })
+);

package/src/utils/signature/constants.mjs

@@ -0,0 +1,12 @@
+// Grabs a method's name
+export const NAME_EXPRESSION = /^['`"]?([^'`": {]+)['`"]?\s*:?\s*/;
+
+// Checks if there's a leading hyphen
+export const LEADING_HYPHEN = /^-\s*/;
+
+// Grabs the default value if present
+export const DEFAULT_EXPRESSION = /\s*\*\*Default:\*\*\s*([^]+)$/i;
+
+// Grabs the parameters from a method's signature
+//  ex/ 'new buffer.Blob([sources[, options]])'.match(PARAM_EXPRESSION) === ['([sources[, options]])', '[sources[, options]]']
+export const PARAM_EXPRESSION = /\(([^)]+)\);?$/;

package/src/utils/signature/parseList.mjs

@@ -0,0 +1,133 @@
+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.
+ * @param {string} text
+ * @param {RegExp} pattern
+ * @param {string} key
+ * @param {Object} current
+ * @returns {string}
+ */
+export const extractPattern = (text, pattern, key, current) => {
+  const match = text.match(pattern)?.[1]?.trim().replace(/\.$/, '');
+
+  if (!match) {
+    return text;
+  }
+
+  current[key] = match;
+  return text.replace(pattern, '');
+};
+
+/**
+ * Parses an individual list item node to extract its properties
+ *
+ * @param {import('@types/mdast').ListItem} child
+ * @returns {import('./types').ParameterList}
+ */
+export function parseListItem(child) {
+  const current = {};
+
+  const subList = child.children.find(UNIST.isLooselyTypedList);
+
+  // Extract and clean raw text from the node, excluding nested lists.
+  // Type annotations serialize back to their `{Type}` source form.
+  current.textRaw = transformNodesToString(
+    child.children.filter(node => node !== subList)
+  )
+    .replace(/\s+/g, ' ')
+    .replace(/<!--.*?-->/gs, '');
+
+  let text = current.textRaw;
+
+  // Identify return items or extract key properties (name, type, default) from the text
+  const starter = text.match(QUERIES.typedListStarters);
+  if (starter) {
+    current.name =
+      starter[1] === 'Returns' ? 'return' : starter[1].toLowerCase();
+    text = text.slice(starter[0].length);
+  } else {
+    text = extractPattern(text, NAME_EXPRESSION, 'name', current);
+  }
+
+  // The type is the item's typeAnnotation node; it's only a type (and not
+  // prose) when its serialized form sits at the head of the remaining text
+  const annotation = child.children
+    .find(node => node.type === 'paragraph')
+    ?.children.find(node => node.type === 'typeAnnotation');
+
+  if (annotation && text.startsWith(`{${annotation.value}}`)) {
+    current.type = annotation.value;
+    text = text.slice(annotation.value.length + 2).replace(/^\s+/, '');
+  }
+
+  text = extractPattern(text, DEFAULT_EXPRESSION, 'default', current);
+
+  // Set the remaining text as the description, removing any leading hyphen
+  current.desc = text.replace(LEADING_HYPHEN, '').trim() || undefined;
+
+  // Parse nested lists (options) recursively if present
+  if (subList) {
+    current.options = subList.children.map(parseListItem);
+  }
+
+  return current;
+}
+
+/**
+ * Parses a list of nodes and updates the corresponding section object with the extracted information.
+ * Handles different section types such as methods, properties, and events differently.
+ * @param {{ [key: string]: unknown }} section - The section object to populate with the parsed values
+ * @param {import('@types/mdast').RootContent[]} nodes
+ */
+export function parseList(section, nodes) {
+  const listIdx = nodes.findIndex(UNIST.isStronglyTypedList);
+  const list = nodes[listIdx];
+
+  const values = list ? list.children.map(parseListItem) : [];
+
+  let removeList = true;
+
+  // Update the section based on its type and parsed values
+  switch (section.type) {
+    case 'ctor':
+      // Constructors are their own signatures
+      leftHandAssign(section, parseSignature(section.textRaw, values));
+      break;
+
+    case 'classMethod':
+    case 'method':
+      // For methods and constructors, parse and attach signatures
+      section.signatures = [parseSignature(section.textRaw, values)];
+      break;
+
+    case 'property':
+      // For properties, update type and other details if values exist
+      if (values.length) {
+        delete values[0].name;
+
+        Object.assign(section, values[0]);
+      }
+      break;
+
+    case 'event':
+      // For events, assign parsed values as parameters
+      section.params = values;
+      break;
+
+    default:
+      removeList = false;
+  }
+
+  if (removeList && list) {
+    nodes.splice(listIdx, 1);
+  }
+}