chore: use @types/mdast (#150)

Author: ovflowd

package-lock.json

@@ -18,14 +18,14 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.13.0",
+    "@types/mdast": "^4.0.4",
     "@types/node": "^22.9.0",
     "eslint": "^9.13.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-jsdoc": "^50.5.0",
     "globals": "^15.11.0",
     "husky": "^9.1.6",
     "lint-staged": "^15.2.10",
-    "mdast": "^3.0.0",
     "prettier": "3.3.3"
   },
   "dependencies": {

package.json

@@ -46,7 +46,7 @@ const buildHeading = ({ data, children }, index, parent) => {
 /**
  * Builds an HTML Stability element
  *
- * @param {import('mdast').Blockquote} node The HTML AST tree of the Stability Index content
+ * @param {import('@types/mdast').Blockquote} node The HTML AST tree of the Stability Index content
  * @param {number} index The index of the current node
  * @param {import('unist').Parent} parent The parent node of the current node
  */
@@ -69,7 +69,7 @@ const buildStability = ({ children, data }, index, parent) => {
 /**
  * Transforms the node Markdown link into an HTML link
  *
- * @param {import('mdast').Html} node The node containing the HTML content
+ * @param {import('@types/mdast').Html} node The node containing the HTML content
  */
 const buildHtmlTypeLink = node => {
   node.value = node.value.replace(

src/generators/legacy-html/utils/buildContent.mjs

@@ -1,4 +1,4 @@
-import { ListItem } from 'mdast';
+import { ListItem } from '@types/mdast';
 
 /**
  * Represents an entry in a hierarchical structure, extending from ApiDocMetadataEntry.

src/generators/legacy-json/types.d.ts

@@ -40,7 +40,7 @@ const extractPattern = (text, pattern, key, current) => {
 /**
  * Parses an individual list item node to extract its properties
  *
- * @param {import('mdast').ListItem} child
+ * @param {import('@types/mdast').ListItem} child
  * @returns {import('../types').ParameterList}
  */
 function parseListItem(child) {
@@ -82,7 +82,7 @@ function parseListItem(child) {
  * 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 {import('../types').Section} section
- * @param {import('mdast').RootContent[]} nodes
+ * @param {import('@types/mdast').RootContent[]} nodes
  */
 export function parseList(section, nodes) {
   const list = nodes[0]?.type === 'list' ? nodes.shift() : null;

src/generators/legacy-json/utils/parseList.mjs

@@ -3,7 +3,7 @@
  * This function processes the node recursively, converting each supported node type
  * to its corresponding Mandoc markup representation. Unsupported node types will be ignored.
  *
- * @param {import("mdast").Node} node - The AST node to be converted to Mandoc format.
+ * @param {import('@types/mdast').Node} node - The AST node to be converted to Mandoc format.
  * @param {boolean} [isListItem=false] - Indicates if the current node is a list item.
  * This parameter is used to correctly format list elements in Mandoc.
  * @returns {string} The Mandoc formatted string representing the given node and its children.

src/generators/man-page/utils/converter.mjs

@@ -24,7 +24,7 @@ const createQueries = () => {
    * Sanitizes the YAML source by returning the inner YAML content
    * and then parsing it into an API Metadata object and updating the current Metadata
    *
-   * @param {import('mdast').Html} node A HTML node containing the YAML content
+   * @param {import('@types/mdast').Html} node A HTML node containing the YAML content
    * @param {ReturnType<import('./metadata.mjs').default>} apiEntryMetadata The API entry Metadata
    */
   const addYAMLMetadata = (node, apiEntryMetadata) => {
@@ -42,7 +42,7 @@ const createQueries = () => {
   /**
    * Parse a Heading node into metadata and updates the current metadata
    *
-   * @param {import('mdast').Heading} node A Markdown heading node
+   * @param {import('@types/mdast').Heading} node A Markdown heading node
    * @param {ReturnType<import('./metadata.mjs').default>} apiEntryMetadata The API entry Metadata
    */
   const setHeadingMetadata = (node, apiEntryMetadata) => {
@@ -57,7 +57,7 @@ const createQueries = () => {
   /**
    * Updates a Markdown link into a HTML link for API docs
    *
-   * @param {import('mdast').Link} node A Markdown link node
+   * @param {import('@types/mdast').Link} node A Markdown link node
    */
   const updateMarkdownLink = node => {
     node.url = node.url.replace(
@@ -72,8 +72,8 @@ const createQueries = () => {
    * Updates a Markdown text containing an API type reference
    * into a Markdown link referencing to the correct API docs
    *
-   * @param {import('mdast').Text} node A Markdown link node
-   * @param {import('mdast').Parent} parent The parent node
+   * @param {import('@types/mdast').Text} node A Markdown link node
+   * @param {import('@types/mdast').Parent} parent The parent node
    */
   const updateTypeReference = (node, parent) => {
     const replacedTypes = node.value
@@ -104,8 +104,8 @@ const createQueries = () => {
   /**
    * Updates a Markdown Link Reference into an actual Link to the Definition
    *
-   * @param {import('mdast').LinkReference} node A link reference node
-   * @param {Array<import('mdast').Definition>} definitions The Definitions of the API Doc
+   * @param {import('@types/mdast').LinkReference} node A link reference node
+   * @param {Array<import('@types/mdast').Definition>} definitions The Definitions of the API Doc
    */
   const updateLinkReference = (node, definitions) => {
     const definition = definitions.find(
@@ -121,7 +121,7 @@ const createQueries = () => {
   /**
    * Parses a Stability Index Entry and updates the current Metadata
    *
-   * @param {import('mdast').Blockquote} node Thead Link Reference Node
+   * @param {import('@types/mdast').Blockquote} node Thead Link Reference Node
    * @param {ReturnType<import('./metadata.mjs').default>} apiEntryMetadata The API entry Metadata
    */
   const addStabilityMetadata = (node, apiEntryMetadata) => {
@@ -204,44 +204,44 @@ createQueries.QUERIES = {
 
 createQueries.UNIST = {
   /**
-   * @param {import('mdast').Blockquote} blockquote
+   * @param {import('@types/mdast').Blockquote} blockquote
    * @returns {boolean}
    */
   isStabilityNode: ({ type, children }) =>
     type === 'blockquote' &&
     createQueries.QUERIES.stabilityIndex.test(transformNodesToString(children)),
   /**
-   * @param {import('mdast').Html} html
+   * @param {import('@types/mdast').Html} html
    * @returns {boolean}
    */
   isYamlNode: ({ type, value }) =>
     type === 'html' && createQueries.QUERIES.yamlInnerContent.test(value),
   /**
-   * @param {import('mdast').Text} text
+   * @param {import('@types/mdast').Text} text
    * @returns {boolean}
    */
   isTextWithType: ({ type, value }) =>
     type === 'text' && createQueries.QUERIES.normalizeTypes.test(value),
   /**
-   * @param {import('mdast').Html} html
+   * @param {import('@types/mdast').Html} html
    * @returns {boolean}
    */
   isHtmlWithType: ({ type, value }) =>
     type === 'html' && createQueries.QUERIES.linksWithTypes.test(value),
   /**
-   * @param {import('mdast').Link} link
+   * @param {import('@types/mdast').Link} link
    * @returns {boolean}
    */
   isMarkdownUrl: ({ type, url }) =>
     type === 'link' && createQueries.QUERIES.markdownUrl.test(url),
   /**
-   * @param {import('mdast').Heading} heading
+   * @param {import('@types/mdast').Heading} heading
    * @returns {boolean}
    */
   isHeading: ({ type, depth }) =>
     type === 'heading' && depth >= 1 && depth <= 5,
   /**
-   * @param {import('mdast').LinkReference} linkReference
+   * @param {import('@types/mdast').LinkReference} linkReference
    * @returns {boolean}
    */
   isLinkReference: ({ type, identifier }) =>

src/queries.mjs

@@ -1,6 +1,6 @@
-import type { Heading, Root } from 'mdast';
+import type { Heading, Root } from '@types/mdast';
 import type { SemVer } from 'semver';
-import type { Parent, Node, Data } from 'unist';
+import type { Data, Node, Parent } from 'unist';
 
 // String serialization of the AST tree
 // @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#tojson_behavior