Add support for some popular transformer plugins (#501)

This adds support for the following transformer plugins:
- `recma-export-filepath`
- `rehype-mdx-title`
- `remark-mdx-frontmatter`

These plugins all follow the same pattern; they expose some form of
metatada as an ESM export. I think these are some of the most popular
plugins that actually affect the editor experience.

I don’t like that support for these plugins is hardcoded. This is only
due to the lack of an alternative. For now I welcome hardcoded support
for other plugins.

I intend to iterate on this to provide a better editor experience for
YAML frontmatter.

Refs #297

Author: remcohaszing

.changeset/lucky-chicken-ring.md

@@ -0,0 +1,5 @@
+---
+'@mdx-js/language-service': minor
+---
+
+Replace `resolveRemarkPlugins` with `remarkPlugins`

.changeset/sad-melons-play.md

@@ -0,0 +1,8 @@
+---
+'@mdx-js/typescript-plugin': patch
+'@mdx-js/language-service': patch
+'@mdx-js/language-server': patch
+'vscode-mdx': patch
+---
+
+Add support for `recma-export-filepath`, `rehype-mdx-title`, and `remark-mdx-frontmatter`

packages/language-server/lib/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 /**
+ * @import {VirtualCodePlugin} from '@mdx-js/language-service'
  * @import {PluggableList} from 'unified'
  */
 
@@ -10,7 +11,7 @@ import process from 'node:process'
 import {
   createMdxLanguagePlugin,
   createMdxServicePlugin,
-  resolveRemarkPlugins
+  resolvePlugins
 } from '@mdx-js/language-service'
 import {
   createConnection,
@@ -82,7 +83,9 @@ connection.onInitialize(async (parameters) => {
    */
   function getLanguagePlugins(tsconfig) {
     /** @type {PluggableList | undefined} */
-    let plugins
+    let remarkPlugins
+    /** @type {VirtualCodePlugin[] | undefined} */
+    let virtualCodePlugins
     let checkMdx = false
     let jsxImportSource = 'react'
 
@@ -101,7 +104,7 @@ connection.onInitialize(async (parameters) => {
       )
       const jiti = createJiti(tsconfig)
 
-      plugins = resolveRemarkPlugins(
+      ;[remarkPlugins, virtualCodePlugins] = resolvePlugins(
         commandLine.raw?.mdx,
         (name) => jiti(name).default
       )
@@ -111,7 +114,8 @@ connection.onInitialize(async (parameters) => {
 
     return [
       createMdxLanguagePlugin(
-        plugins || defaultPlugins,
+        remarkPlugins || defaultPlugins,
+        virtualCodePlugins,
         checkMdx,
         jsxImportSource
       )

packages/language-service/README.md

@@ -19,7 +19,7 @@
 * [API](#api)
   * [`createMdxLanguagePlugin([plugins][, checkMdx][, jsxImportSource])`](#createmdxlanguagepluginplugins-checkmdx-jsximportsource)
   * [`createMdxServicePlugin(options)`](#createmdxservicepluginoptions)
-  * [`resolveRemarkPlugins(mdxConfig, resolvePlugin)`](#resolveremarkpluginsmdxconfig-resolveplugin)
+  * [`resolvePlugins(mdxConfig, resolvePlugin)`](#resolvepluginsmdxconfig-resolveplugin)
 * [Compatibility](#compatibility)
 * [Types](#types)
 * [Security](#security)
@@ -57,7 +57,7 @@ In Deno with [`esm.sh`][esmsh]:
 import {
   createMdxLanguagePlugin,
   createMdxServicePlugin,
-  resolveRemarkPlugins
+  resolvePlugins
 } from 'https://esm.sh/@mdx-js/language-service'
 ```
 
@@ -68,7 +68,7 @@ In browsers with [`esm.sh`][esmsh]:
   import {
     createMdxLanguagePlugin,
     createMdxServicePlugin,
-    resolveRemarkPlugins
+    resolvePlugins
   } from 'https://esm.sh/@mdx-js/language-service?bundle'
 </script>
 ```
@@ -136,9 +136,9 @@ The following commands are supported:
 
 The Volar service plugin for MDX files.
 
-### `resolveRemarkPlugins(mdxConfig, resolvePlugin)`
+### `resolvePlugins(mdxConfig, resolvePlugin)`
 
-Resolve remark plugins from TypeScript’s parsed command line options.
+Resolve plugins from TypeScript’s parsed command line options.
 
 #### Parameters
 
@@ -149,8 +149,14 @@ Resolve remark plugins from TypeScript’s parsed command line options.
 
 #### Returns
 
-An array of resolved plugins, or `undefined` in case of an invalid
-configuration.
+A tuple where the first item is n array of resolved plugins,
+or `undefined` in case of an invalid configuration.
+The second item is an array of supported transformer plugins.
+The supported transformer plugins are:
+
+* [`recma-export-filepath`](https://github.com/remcohaszing/recma-export-filepath)
+* [`rehype-mdx-title`](https://github.com/remcohaszing/rehype-mdx-title)
+* [`remark-mdx-frontmatter`](https://github.com/remcohaszing/remark-mdx-frontmatter)
 
 ## Compatibility
 

packages/language-service/lib/index.js

@@ -1,3 +1,7 @@
+/**
+ * @typedef {import('./plugins/plugin.js').VirtualCodePlugin} VirtualCodePlugin
+ */
+
 export {createMdxLanguagePlugin} from './language-plugin.js'
 export {createMdxServicePlugin} from './service-plugin.js'
-export {resolveRemarkPlugins} from './tsconfig.js'
+export {resolvePlugins} from './tsconfig.js'

packages/language-service/lib/language-plugin.js

@@ -4,6 +4,7 @@
  * @import {LanguagePlugin} from '@volar/language-service'
  * @import {PluggableList} from 'unified'
  * @import {URI} from 'vscode-uri'
+ * @import {VirtualCodePlugin} from './plugins/plugin.js'
  */
 
 import remarkMdx from 'remark-mdx'
@@ -14,9 +15,10 @@ import {VirtualMdxCode} from './virtual-code.js'
 /**
  * Create a [Volar](https://volarjs.dev) language plugin to support MDX.
  *
- * @param {PluggableList} [plugins]
+ * @param {PluggableList} [remarkPlugins]
  *   A list of remark syntax plugins. Only syntax plugins are supported.
  *   Transformers are unused.
+ * @param {VirtualCodePlugin[]} [virtualCodePlugins]
  * @param {boolean} checkMdx
  *   If true, check MDX files strictly.
  * @param {string} jsxImportSource
@@ -25,13 +27,14 @@ import {VirtualMdxCode} from './virtual-code.js'
  *   A Volar language plugin to support MDX.
  */
 export function createMdxLanguagePlugin(
-  plugins,
+  remarkPlugins,
+  virtualCodePlugins,
   checkMdx = false,
   jsxImportSource = 'react'
 ) {
   const processor = unified().use(remarkParse).use(remarkMdx)
-  if (plugins) {
-    processor.use(plugins)
+  if (remarkPlugins) {
+    processor.use(remarkPlugins)
   }
 
   processor.freeze()
@@ -48,6 +51,7 @@ export function createMdxLanguagePlugin(
         return new VirtualMdxCode(
           snapshot,
           processor,
+          virtualCodePlugins || [],
           checkMdx,
           jsxImportSource
         )

packages/language-service/lib/plugins/plugin.js

@@ -0,0 +1,17 @@
+/**
+ * @import {Nodes} from 'mdast'
+ */
+
+/**
+ * @typedef VirtualCodePluginObject
+ *   An object returned by a virtual code plugin.
+ * @property {(node: Nodes) => undefined} [visit]
+ *   Visit an mdast node.
+ * @property {() => string} finalize
+ *   Generate the JavaScript string to insert into the virtual code.
+ */
+
+/**
+ * @typedef {() => VirtualCodePluginObject} VirtualCodePlugin
+ *   An internal plugin for MDX analyzer that represents an MDX plugin.
+ */

packages/language-service/lib/plugins/recma-export-filepath.js

@@ -0,0 +1,24 @@
+/**
+ * @import {VirtualCodePlugin} from './plugin.js'
+ */
+
+/**
+ * @param {unknown} options
+ * @returns {VirtualCodePlugin}
+ */
+export function recmaExportFilepath(options) {
+  const opts = typeof options === 'object' && options !== null ? options : {}
+  const name = 'name' in opts ? String(opts.name) : 'filepath'
+
+  return () => {
+    return {
+      finalize() {
+        return (
+          '/** Generated by [recma-export-filepath](https://github.com/remcohaszing/recma-export-filepath) */\nexport const ' +
+          name +
+          " = /** @type {string} */ ('')"
+        )
+      }
+    }
+  }
+}

packages/language-service/lib/plugins/rehype-mdx-title.js

@@ -0,0 +1,33 @@
+/**
+ * @import {VirtualCodePlugin} from './plugin.js'
+ */
+
+/**
+ * @param {unknown} options
+ * @returns {VirtualCodePlugin}
+ */
+export function rehypeMdxTitle(options) {
+  const opts = typeof options === 'object' && options !== null ? options : {}
+  const maxRank = 'maxRank' in opts ? Number(opts.maxRank) : 1
+  const name = 'name' in opts ? String(opts.name) : 'title'
+
+  return () => {
+    let hasTitle = false
+
+    return {
+      visit(node) {
+        hasTitle ||= node.type === 'heading' && node.depth <= maxRank
+      },
+
+      finalize() {
+        return (
+          '/** Generated by [rehype-mdx-title](https://github.com/remcohaszing/rehype-mdx-title) */\nexport const ' +
+          name +
+          ' = /** @type {string' +
+          (hasTitle ? '' : ' | undefined') +
+          "} */ ('')"
+        )
+      }
+    }
+  }
+}

packages/language-service/lib/plugins/remark-mdx-frontmatter.js

@@ -0,0 +1,32 @@
+/**
+ * @import {VirtualCodePlugin} from './plugin.js'
+ */
+
+/**
+ * @param {unknown} options
+ * @returns {VirtualCodePlugin}
+ */
+export function remarkMdxFrontmatter(options) {
+  const opts = typeof options === 'object' && options !== null ? options : {}
+  const name = 'name' in opts ? String(opts.name) : 'frontmatter'
+
+  return () => {
+    let hasFrontmatter = false
+
+    return {
+      visit(node) {
+        hasFrontmatter ||= node.type === 'toml' || node.type === 'yaml'
+      },
+
+      finalize() {
+        return (
+          '/** Generated by [remark-mdx-frontmatter](https://github.com/remcohaszing/remark-mdx-frontmatter) */\nexport const ' +
+          name +
+          ' = /** @type {' +
+          (hasFrontmatter ? 'any' : 'undefined') +
+          '} */ (undefined)'
+        )
+      }
+    }
+  }
+}