@doc-kit/core 1.2.0 → 1.3.0

package/src/utils/highlighter.mjs

@@ -1,198 +0,0 @@
-'use strict';
-
-import { endianness } from 'node:os';
-
-import createHighlighter from '@node-core/rehype-shiki';
-import { h as createElement } from 'hastscript';
-import { SKIP, visit } from 'unist-util-visit';
-
-import shikiConfig from '../../shiki.config.mjs';
-
-// This is what Remark will use as prefix within a <pre> className
-// to attribute the current language of the <pre> element
-const languagePrefix = 'language-';
-
-/**
- * Creates a toolbar element with a language label and copy button.
- *
- * @param {string} languageId - The language identifier for the code block.
- * @returns {import('hast').Element} The toolbar element.
- */
-function createToolbarElement(languageId) {
-  return createElement('div', { class: 'code-toolbar' }, [
-    createElement('span', { class: 'code-language' }, languageId),
-    createElement('button', { class: 'copy-button' }, 'copy'),
-  ]);
-}
-
-/**
- * Checks if the given node is a valid code element.
- *
- * @param {import('unist').Node} node - The node to be verified.
- *
- * @return {boolean} - True when it is a valid code element, false otherwise.
- */
-function isCodeBlock(node) {
-  return Boolean(
-    node?.tagName === 'pre' && node?.children[0].tagName === 'code'
-  );
-}
-
-export const highlighter = await createHighlighter({
-  // riscv64 with sv39 has limited virtual memory space, where creating
-  // too many (>20) wasm memory instances fails.
-  // https://github.com/nodejs/node/pull/60591
-  //
-  // The wasm highlighter is currently not compatible with big endian.
-  // https://github.com/nodejs/node/pull/62512#issuecomment-4243469950
-  wasm: process.arch !== 'riscv64' && endianness() === 'LE',
-});
-
-/**
- * Creates a HAST transformer for Shiki which is used for transforming our codeboxes
- *
- * @deprecated This is used only for the legacy-html generator, please use `@node-core/rehype-shiki` directly instead.
- *
- * @type {import('unified').Plugin}
- */
-export default function rehypeShikiji() {
-  /**
-   * @param {import('hast').Root} tree - The HAST tree to be transformed.
-   */
-  return function (tree) {
-    visit(tree, 'element', (node, index, parent) => {
-      // We only want to process <pre>...</pre> elements
-      if (!parent || index == null || node.tagName !== 'pre') {
-        return;
-      }
-
-      // We want the contents of the <pre> element, hence we attempt to get the first child
-      const preElement = node.children[0];
-
-      // If thereÄs nothing inside the <pre> element... What are we doing here?
-      if (!preElement || !preElement.properties) {
-        return;
-      }
-
-      // Ensure that we're not visiting a <code> element but it's inner contents
-      // (keep iterating further down until we reach where we want)
-      if (preElement.type !== 'element' || preElement.tagName !== 'code') {
-        return;
-      }
-
-      // Get the <pre> element class names
-      const preClassNames = preElement.properties.className;
-
-      // The current classnames should be an array and it should have a length
-      if (typeof preClassNames !== 'object' || preClassNames.length === 0) {
-        return;
-      }
-
-      // We want to retrieve the language class name from the class names
-      const codeLanguage = preClassNames.find(
-        c => typeof c === 'string' && c.startsWith(languagePrefix)
-      );
-
-      // If we didn't find any `language-` classname then we shouldn't highlight
-      if (typeof codeLanguage !== 'string') {
-        return;
-      }
-
-      // Grabs the relevant alias/name of the language
-      const languageId = codeLanguage.slice(languagePrefix.length);
-
-      // Parses the <pre> contents and returns a HAST tree with the highlighted code
-      const { children } = highlighter.shiki.codeToHast(
-        preElement.children[0].value,
-        {
-          lang: languageId,
-          // Allows support for dual themes (light, dark) for Shiki
-          themes: { light: shikiConfig.themes[0], dark: shikiConfig.themes[1] },
-        }
-      );
-
-      // Adds the original language back to the <pre> element
-      children[0].properties.class = `${children[0].properties.class} ${codeLanguage}`;
-
-      // Adds the toolbar (language label + copy button) to the <pre> element
-      children[0].children.push(createToolbarElement(languageId));
-
-      // Replaces the <pre> element with the updated one
-      parent.children.splice(index, 1, ...children);
-    });
-
-    visit(tree, 'element', (_, index, parent) => {
-      const codeElements = [];
-
-      let currentIndex = index;
-
-      while (isCodeBlock(parent?.children[currentIndex])) {
-        const preElement = parent?.children[currentIndex];
-        const codeElement = preElement.children[0];
-
-        // We should get the language name from the class name
-        if (preElement.properties.class?.length) {
-          const className = preElement.properties.class;
-          const matches = className.match(/language-(?<language>.*)/);
-          const language = matches?.groups.language ?? 'text';
-
-          // For this iteration of our code, we only support multi-code tab for
-          // JavaScript languages for Node.js (CJS / MJS)
-          if (language === 'cjs' || language === 'mjs') {
-            // We patch up Shiki's `pre` element properties into the `code` element
-            // since we want to keep the original properties
-            codeElement.properties.class = `${className} ${language}`;
-            codeElement.properties.style = preElement.properties.style;
-            codeElement.properties.language = language;
-
-            // Add the code element to the pre children
-            codeElements.push(codeElement);
-          }
-        }
-
-        currentIndex += 1;
-
-        // Since we only support CJS/MJS switch, we should have exactly 2 elements
-        // with different languages in order to create a switchable code tab
-        if (
-          codeElements.length === 2 &&
-          codeElements[0].properties?.language !==
-            codeElements[1].properties?.language
-        ) {
-          const switchablePreElement = createElement(
-            'pre',
-            {
-              // We grab Shiki's styling from the code tag
-              // back to the pre element tag to ensure consistency
-              style: codeElements[0].properties.style,
-              class: 'shiki',
-            },
-            [
-              createElement('input', {
-                class: 'js-flavor-toggle',
-                type: 'checkbox',
-                // If the CJS code block is the first one, then we should keep
-                // the checkbox checked so that it highglit the CJS by default
-                checked: codeElements[0].properties.language === 'cjs',
-              }),
-              ...codeElements,
-              createToolbarElement('javascript'),
-            ]
-          );
-
-          // This removes all the original code Elements and adds a new CodeTab Element
-          // at the original start of the first Code Element
-          parent.children.splice(
-            index,
-            currentIndex - index,
-            switchablePreElement
-          );
-
-          // Prevent visiting the code block children and for the next N Elements
-          // since all of them belong to this CodeTabs Element
-          return [SKIP];
-        }
-      }
-    });
-  };
-}

package/src/utils/remark-shiki.mjs

@@ -1,29 +0,0 @@
-'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

@@ -1,90 +0,0 @@
-'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 { lazy } from './misc.mjs';
-import { typeAnnotationToHast } from './type-annotations/hast.mjs';
-import remarkTypeAnnotations from './type-annotations/remark.mjs';
-
-// 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)
- * 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).use(remarkStringify)
-);
-
-/**
- * Retrieves an instance of Remark configured to output stringified HTML code
- */
-export const getRemarkRehype = lazy(() =>
-  unified()
-    .use(remarkParse)
-    .use(remarkRehype, rehypeOptions)
-    .use(rehypeStringify, { allowDangerousHtml: true })
-);