@doc-kit/core 0.0.0

package/src/utils/signature/parseSignature.mjs

@@ -0,0 +1,208 @@
+'use strict';
+
+import { PARAM_EXPRESSION } from './constants.mjs';
+
+const OPTIONAL_LEVEL_CHANGES = { '[': 1, ']': -1 };
+
+/**
+ * @param {Number} depth
+ * @param {String} char
+ * @returns {Number}
+ */
+const updateDepth = (depth, char) =>
+  depth + (OPTIONAL_LEVEL_CHANGES[char] || 0);
+
+/**
+ * @param {string} parameterName
+ * @param {number} optionalDepth
+ * @returns {[string, number, boolean]}
+ */
+export function parseNameAndOptionalStatus(parameterName, optionalDepth) {
+  // Let's check if the parameter is optional & grab its name at the same time.
+  //  We need to see if there's any leading brackets in front of the parameter
+  //  name. While we're doing that, we can also get the index where the
+  //  parameter's name actually starts at.
+
+  // Find the starting index where the name begins
+  const startingIdx = [...parameterName].findIndex(
+    char => !OPTIONAL_LEVEL_CHANGES[char]
+  );
+
+  // Update optionalDepth based on leading brackets
+  optionalDepth = [...parameterName.slice(0, startingIdx)].reduce(
+    updateDepth,
+    optionalDepth
+  );
+
+  // Find the ending index where the name ends
+  const endingIdx = [...parameterName].findLastIndex(
+    char => !OPTIONAL_LEVEL_CHANGES[char]
+  );
+
+  // Extract the actual parameter name
+  const actualName = parameterName.slice(startingIdx, endingIdx + 1);
+  const isParameterOptional = optionalDepth > 0;
+
+  // Update optionalDepth based on trailing brackets
+  // These apply to the NEXT parameter
+  optionalDepth = [...parameterName.slice(endingIdx + 1)].reduce(
+    updateDepth,
+    optionalDepth
+  );
+
+  return [actualName, optionalDepth, isParameterOptional];
+}
+
+/**
+ * @param {string} parameterName
+ * @returns {[string, string | undefined]}
+ */
+export function parseDefaultValue(parameterName) {
+  /**
+   * @type {string | undefined}
+   */
+  let defaultValue;
+  const equalSignPos = parameterName.indexOf('=');
+
+  if (equalSignPos !== -1) {
+    // We do have a default value, let's extract it
+    defaultValue = parameterName.substring(equalSignPos).trim();
+
+    // Let's remove the default value from the parameter name
+    parameterName = parameterName.substring(0, equalSignPos);
+  }
+
+  return [parameterName, defaultValue];
+}
+
+/**
+ * @param {string} parameterName
+ * @param {number} index
+ * @param {Array<import('./types.d.ts').ParameterList>} markdownParameters
+ * @returns {import('./types.d.ts').Parameter}
+ */
+export function findParameter(parameterName, index, markdownParameters) {
+  const parameter = markdownParameters[index];
+  if (parameter?.name === parameterName) {
+    return parameter;
+  }
+
+  // Method likely has multiple signatures, something like
+  //  `new Console(stdout[, stderr][, ignoreErrors])` and `new Console(options)`
+  // Try to find the parameter that this is being shared with
+  for (const property of markdownParameters) {
+    if (property.name === parameterName) {
+      return property;
+    }
+
+    const matchingOption = property.options?.find(
+      option => option.name === parameterName
+    );
+    if (matchingOption) {
+      return { ...matchingOption };
+    }
+  }
+
+  // Default return if no matches are found
+  return { name: parameterName };
+}
+
+/**
+ * @param {string[]} declaredParameters
+ * @param {Array<import('./types.d.ts').ParameterList>} markdownParameters
+ */
+export function parseParameters(declaredParameters, markdownParameters) {
+  /**
+   * @type {Array<import('./types.d.ts').Parameter>}
+   */
+  let parameters = [];
+
+  let optionalDepth = 0;
+
+  declaredParameters.forEach((parameterName, i) => {
+    /**
+     * @example 'length]]'
+     * @example 'arrayBuffer['
+     * @example '[sources['
+     * @example 'end'
+     */
+    parameterName = parameterName.trim();
+
+    // We need to do three things here:
+    //  1. Determine the declared parameters' name
+    //  2. Determine if the parameter is optional
+    //  3. Determine if the parameter has a default value
+
+    /**
+     * This will handle the first and second thing for us
+     * @type {boolean}
+     */
+    let isParameterOptional;
+    [parameterName, optionalDepth, isParameterOptional] =
+      parseNameAndOptionalStatus(parameterName, optionalDepth);
+
+    /**
+     * Now let's work on the third thing
+     * @type {string | undefined}
+     */
+    let defaultValue;
+    [parameterName, defaultValue] = parseDefaultValue(parameterName);
+
+    const parameter = findParameter(parameterName, i, markdownParameters);
+
+    if (isParameterOptional) {
+      parameter.optional = true;
+    }
+
+    if (defaultValue) {
+      parameter.default = defaultValue;
+    }
+
+    parameters.push(parameter);
+  });
+
+  return parameters;
+}
+
+/**
+ * @param {string} textRaw Something like `new buffer.Blob([sources[, options]])`
+ * @param {Array<import('./types.d.ts').ParameterList} markdownParameters The properties in the AST
+ * @returns {import('./types.d.ts').MethodSignature | undefined}
+ */
+export default (textRaw, markdownParameters) => {
+  /**
+   * @type {import('./types.d.ts').MethodSignature}
+   */
+  const signature = { params: [] };
+
+  // Find the return/extends value & filter it out
+  markdownParameters = markdownParameters.filter(value => {
+    if (value.name === 'return' || value.name === 'extends') {
+      signature[value.name] = value;
+      return false;
+    }
+
+    return true;
+  });
+
+  /**
+   * Extract the parameters from the method's declaration
+   * @example `[sources[, options]]`
+   */
+  let [, declaredParameters] =
+    textRaw.replace(/^`|`$/g, '').match(PARAM_EXPRESSION) || [];
+
+  if (!declaredParameters) {
+    return signature;
+  }
+
+  /**
+   * @type {string[]}
+   * @example ['sources[,', 'options]]']
+   */
+  declaredParameters = declaredParameters.split(',');
+
+  signature.params = parseParameters(declaredParameters, markdownParameters);
+
+  return signature;
+};

package/src/utils/signature/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Represents a parameter for methods or functions.
+ */
+export interface Parameter {
+  /**
+   * The name of the parameter.
+   */
+  name: string;
+
+  /**
+   * Indicates if the parameter is optional.
+   */
+  optional?: boolean;
+
+  /**
+   * The default value for the parameter.
+   */
+  default?: string;
+}
+
+/**
+ * Represents a method signature, including its parameters and return type.
+ */
+export interface MethodSignature {
+  /**
+   * A list of parameters for the method.
+   */
+  params: Parameter[];
+
+  /**
+   * The return type of the method.
+   */
+  return?: Parameter;
+}
+
+/**
+ * Represents a list of parameters.
+ */
+export interface ParameterList {
+  /**
+   * Raw parameter description
+   */
+  textRaw: string;
+
+  /**
+   * A short description of the parameter.
+   */
+  desc?: string;
+
+  /**
+   * The name of the parameter.
+   */
+  name: string;
+
+  /**
+   * The type of the parameter (E.G. string, boolean).
+   */
+  type?: string;
+
+  /**
+   * The default value.
+   */
+  default?: string;
+
+  options?: ParameterList;
+}

package/src/utils/swc.mjs

@@ -0,0 +1,34 @@
+'use strict';
+
+// TODO(@avivkeller): Once oxc-parser supports WASM, or the
+// bindings we need, remove this in favor of it. It's much
+// faster.
+//
+// For now, however, this is our walker :-)
+
+/**
+ * @param {unknown} node
+ * @param {((node: { type: string }) => void) | Record<string, (node: never) => void>} visitors
+ */
+export const walk = (node, visitors) => {
+  if (node === null || typeof node !== 'object') {
+    return;
+  }
+
+  if (Array.isArray(node)) {
+    node.forEach(child => walk(child, visitors));
+    return;
+  }
+
+  if (typeof visitors === 'function') {
+    visitors(node);
+  } else {
+    visitors[node.type]?.(node);
+  }
+
+  for (const [key, value] of Object.entries(node)) {
+    if (key !== 'span' && key !== 'loc') {
+      walk(value, visitors);
+    }
+  }
+};

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

@@ -0,0 +1,115 @@
+'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.
+ *
+ * @param {string} value The type text
+ * @param {Array<{ start: number, end: number, href: string }>} links Sorted, disjoint ranges
+ * @returns {Array<import('hast').ElementContent>}
+ */
+const buildLinkedChildren = (value, links) => {
+  const children = [];
+  let cursor = 0;
+
+  for (const { start, end, href } of links) {
+    if (start > cursor) {
+      children.push({ type: 'text', value: value.slice(cursor, start) });
+    }
+
+    children.push({
+      type: 'element',
+      tagName: 'a',
+      properties: { href, className: ['type-link'] },
+      children: [{ type: 'text', value: value.slice(start, end) }],
+    });
+
+    cursor = end;
+  }
+
+  if (cursor < value.length) {
+    children.push({ type: 'text', value: value.slice(cursor) });
+  }
+
+  return children;
+};
+
+/**
+ * Minimal mdast→hast handler for `typeAnnotation` nodes: one
+ * `<code class="type">` whose resolved identifiers are plain `<a>` links.
+ * No syntax highlighting — used by the legacy generators.
+ *
+ * @param {import('mdast-util-to-hast').State} state
+ * @param {import('mdast').Node} node
+ * @returns {import('hast').Element}
+ */
+export const typeAnnotationToHast = (state, node) => {
+  const result = {
+    type: 'element',
+    tagName: 'code',
+    properties: { className: ['type'] },
+    children: buildLinkedChildren(node.value, node.data?.links ?? []),
+  };
+
+  state.patch(node, result);
+
+  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/mdast.mjs

@@ -0,0 +1,75 @@
+'use strict';
+
+// A backslash escape before ASCII punctuation (CommonMark's escapable set).
+// The tokenizer captures the raw source, so legacy escapes like `{string\[]}`
+// and the mandatory `\|` inside GFM table cells must be decoded here.
+const CHARACTER_ESCAPE = /\\([!-/:-@[-`{-~])/g;
+
+// A single union separator, with any surrounding whitespace. Lookarounds
+// exclude `||` (logical OR in default-value prose).
+const UNION_SEPARATOR = /(?<!\|)\s*\|\s*(?!\|)/g;
+
+/**
+ * Creates the mdast-util-from-markdown extension that compiles
+ * `typeAnnotation` tokens into `{ type: 'typeAnnotation', value }` nodes.
+ *
+ * The stored `value` is the canonical, single-line, unescaped TypeScript type
+ * text with union separators spaced (`A | B`); link offsets computed later
+ * are relative to it.
+ *
+ * @returns {import('mdast-util-from-markdown').Extension}
+ */
+export const typeAnnotationFromMarkdown = () => ({
+  enter: {
+    /**
+     * @this {import('mdast-util-from-markdown').CompileContext}
+     * @param {import('micromark-util-types').Token} token
+     */
+    typeAnnotation(token) {
+      this.enter({ type: 'typeAnnotation', value: '' }, token);
+    },
+  },
+  exit: {
+    /**
+     * @this {import('mdast-util-from-markdown').CompileContext}
+     * @param {import('micromark-util-types').Token} token
+     */
+    typeAnnotationValue(token) {
+      const node = this.stack.at(-1);
+      const chunk = this.sliceSerialize(token);
+
+      // Chunks are split by interior line endings; re-join with a space
+      node.value = node.value ? `${node.value} ${chunk}` : chunk;
+    },
+    /**
+     * @this {import('mdast-util-from-markdown').CompileContext}
+     * @param {import('micromark-util-types').Token} token
+     */
+    typeAnnotation(token) {
+      const node = this.stack.at(-1);
+
+      node.value = node.value
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(CHARACTER_ESCAPE, '$1')
+        .replace(UNION_SEPARATOR, ' | ');
+
+      this.exit(token);
+    },
+  },
+});
+
+/**
+ * Creates the mdast-util-to-markdown extension that serializes
+ * `typeAnnotation` nodes back to their `{...}` source form.
+ *
+ * @returns {import('mdast-util-to-markdown').Options}
+ */
+export const typeAnnotationToMarkdown = () => ({
+  handlers: {
+    /**
+     * @param {{ value: string }} node
+     */
+    typeAnnotation: node => `{${node.value}}`,
+  },
+});

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

@@ -0,0 +1,24 @@
+'use strict';
+
+import {
+  typeAnnotationFromMarkdown,
+  typeAnnotationToMarkdown,
+} from './mdast.mjs';
+import { typeAnnotationSyntax } from './syntax.mjs';
+
+/**
+ * Remark plugin that teaches the parser to treat any balanced `{...}` span in
+ * text as a `typeAnnotation` node whose value is a TypeScript type expression.
+ *
+ * Only registered on the non-MDX pipeline — in MDX, `{...}` is a real
+ * expression and is handled by remark-mdx instead.
+ *
+ * @this {import('unified').Processor}
+ */
+export default function remarkTypeAnnotations() {
+  const data = this.data();
+
+  (data.micromarkExtensions ??= []).push(typeAnnotationSyntax());
+  (data.fromMarkdownExtensions ??= []).push(typeAnnotationFromMarkdown());
+  (data.toMarkdownExtensions ??= []).push(typeAnnotationToMarkdown());
+}

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

@@ -0,0 +1,188 @@
+'use strict';
+
+const LEFT_CURLY_BRACE = '{'.charCodeAt(0);
+const RIGHT_CURLY_BRACE = '}'.charCodeAt(0);
+const DOLLAR_SIGN = '$'.charCodeAt(0);
+const SPACE = ' '.charCodeAt(0);
+
+// The type starters that are punctuation: `_` and `$` (identifiers), the
+// openers of parenthesized, tuple, object, generic and string-literal types,
+// the leading `-` of a negative numeric literal, the leading `&`/`|` of an
+// intersection or union, and `\` (a legacy escape, decoded further down the
+// pipeline). Alphanumeric and non-ASCII starters are handled by `isTypeStart`.
+const TYPE_STARTER_PUNCTUATION = new Set(
+  [...'_$([{<\'"`-&|\\'].map(character => character.charCodeAt(0))
+);
+
+/**
+ * micromark preprocesses `\r`, `\n` and `\r\n` into virtual codes below -2
+ * (and represents EOF as `null`).
+ *
+ * @param {import('micromark-util-types').Code} code
+ */
+const isLineEnding = code => code !== null && code < -2;
+
+/**
+ * A tab is preprocessed into -2, followed by -1 for each column it expands to.
+ *
+ * @param {import('micromark-util-types').Code} code
+ */
+const isSpace = code => code === SPACE || code === -1 || code === -2;
+
+/**
+ * @param {import('micromark-util-types').Code} code
+ */
+const isAsciiAlphanumeric = code =>
+  (code >= 0x30 && code <= 0x39) || // 0-9
+  (code >= 0x41 && code <= 0x5a) || // A-Z
+  (code >= 0x61 && code <= 0x7a); // a-z
+
+/**
+ * Whether a type expression may begin with this character: an identifier or
+ * numeric literal (alphanumeric or non-ASCII) or one of the punctuation
+ * starters above. Prose that happens to sit between two braces (as in url.md's
+ * `U+007B ({), and U+007D (}).`) starts with punctuation that no type can, so
+ * this keeps such spans out.
+ *
+ * @param {import('micromark-util-types').Code} code
+ */
+const isTypeStart = code =>
+  code !== null &&
+  (isAsciiAlphanumeric(code) ||
+    // Non-ASCII identifier characters
+    code >= 0x80 ||
+    TYPE_STARTER_PUNCTUATION.has(code));
+
+/**
+ * A `{` directly after `$` is prose about template literals, not a type
+ * annotation.
+ *
+ * @param {import('micromark-util-types').Code} code
+ */
+const previous = code => code !== DOLLAR_SIGN;
+
+/**
+ * Tokenizes a balanced `{...}` span as a single `typeAnnotation` token.
+ *
+ * The outer braces become `typeAnnotationMarker` tokens; everything between
+ * them becomes `typeAnnotationValue` chunks (one per line). An unbalanced or
+ * empty span, or one whose content cannot start a type, fails the construct,
+ * so the `{` falls back to literal text.
+ *
+ * @type {import('micromark-util-types').Tokenizer}
+ */
+function tokenizeTypeAnnotation(effects, ok, nok) {
+  // Nesting depth of inner `{`/`}` pairs (the wrapping pair is not counted)
+  let depth = 0;
+  // `{}` (no content at all) must not become an annotation
+  let hasContent = false;
+
+  /**
+   * At the opening `{`.
+   *
+   * @type {import('micromark-util-types').State}
+   */
+  const start = code => {
+    effects.enter('typeAnnotation');
+    effects.enter('typeAnnotationMarker');
+    effects.consume(code);
+    effects.exit('typeAnnotationMarker');
+
+    return between;
+  };
+
+  /**
+   * At a position where a value chunk may start: right after the opening
+   * brace or after an interior line ending.
+   *
+   * @type {import('micromark-util-types').State}
+   */
+  const between = code => {
+    if (code === null) {
+      return nok(code);
+    }
+
+    if (code === RIGHT_CURLY_BRACE && depth === 0) {
+      return hasContent ? finish(code) : nok(code);
+    }
+
+    if (isLineEnding(code)) {
+      effects.enter('lineEnding');
+      effects.consume(code);
+      effects.exit('lineEnding');
+
+      return between;
+    }
+
+    effects.enter('typeAnnotationValue');
+
+    return value(code);
+  };
+
+  /**
+   * Inside a value chunk.
+   *
+   * @type {import('micromark-util-types').State}
+   */
+  const value = code => {
+    if (
+      code === null ||
+      isLineEnding(code) ||
+      (code === RIGHT_CURLY_BRACE && depth === 0)
+    ) {
+      effects.exit('typeAnnotationValue');
+
+      return between(code);
+    }
+
+    if (!hasContent && !isSpace(code)) {
+      if (!isTypeStart(code)) {
+        return nok(code);
+      }
+
+      hasContent = true;
+    }
+
+    if (code === LEFT_CURLY_BRACE) {
+      depth++;
+    } else if (code === RIGHT_CURLY_BRACE) {
+      depth--;
+    }
+
+    effects.consume(code);
+
+    return value;
+  };
+
+  /**
+   * At the closing `}`.
+   *
+   * @type {import('micromark-util-types').State}
+   */
+  const finish = code => {
+    effects.enter('typeAnnotationMarker');
+    effects.consume(code);
+    effects.exit('typeAnnotationMarker');
+    effects.exit('typeAnnotation');
+
+    return ok;
+  };
+
+  return start;
+}
+
+/**
+ * Creates the micromark syntax extension that recognizes `{...}` type
+ * annotations in text.
+ *
+ * @returns {import('micromark-util-types').Extension}
+ */
+export const typeAnnotationSyntax = () => ({
+  text: {
+    [LEFT_CURLY_BRACE]: {
+      name: 'typeAnnotation',
+      tokenize: tokenizeTypeAnnotation,
+      previous,
+    },
+  },
+});