Fix some bugs, refactor some code

*   Add more docs to JSDoc
*   Add support for `null` in input of API types
*   Backport syntax-tree/mdast-util-to-markdown@cf7cf8f
*   Backport syntax-tree/mdast-util-to-markdown@eed5115
*   Fix typo, don’t allow `\n` in math meta

Author: wooorm

lib/index.js

@@ -8,19 +8,25 @@
  * @typedef {import('../index.js').InlineMath} InlineMath
  *
  * @typedef ToOptions
- * @property {boolean} [singleDollarTextMath=true]
- *   Whether to support math (text) with a single dollar (`boolean`, default:
- *   `true`).
+ *   Configuration.
+ * @property {boolean | null | undefined} [singleDollarTextMath=true]
+ *   Whether to support math (text) with a single dollar.
+ *
  *   Single dollars work in Pandoc and many other places, but often interfere
  *   with “normal” dollars in text.
+ *   If you turn this off, you can still use two or more dollars for text math.
  */
 
 import {longestStreak} from 'longest-streak'
 import {safe} from 'mdast-util-to-markdown/lib/util/safe.js'
 import {track} from 'mdast-util-to-markdown/lib/util/track.js'
+import {patternCompile} from 'mdast-util-to-markdown/lib/util/pattern-compile.js'
 
 /**
+ * Create an extension for `mdast-util-from-markdown`.
+ *
  * @returns {FromMarkdownExtension}
+ *   Extension for `mdast-util-from-markdown`.
  */
 export function mathFromMarkdown() {
   return {
@@ -144,11 +150,15 @@ export function mathFromMarkdown() {
 }
 
 /**
- * @param {ToOptions} [options]
+ * Create an extension for `mdast-util-to-markdown`.
+ *
+ * @param {ToOptions | null | undefined} [options]
+ *   Configuration.
  * @returns {ToMarkdownExtension}
+ *   Extension for `mdast-util-to-markdown`.
  */
-export function mathToMarkdown(options = {}) {
-  let single = options.singleDollarTextMath
+export function mathToMarkdown(options) {
+  let single = (options || {}).singleDollarTextMath
 
   if (single === null || single === undefined) {
     single = true
@@ -158,15 +168,14 @@ export function mathToMarkdown(options = {}) {
 
   return {
     unsafe: [
-      {character: '\r', inConstruct: ['mathFlowMeta']},
-      {character: '\r', inConstruct: ['mathFlowMeta']},
-      single
-        ? {character: '$', inConstruct: ['mathFlowMeta', 'phrasing']}
-        : {
-            character: '$',
-            after: '\\$',
-            inConstruct: ['mathFlowMeta', 'phrasing']
-          },
+      {character: '\r', inConstruct: 'mathFlowMeta'},
+      {character: '\n', inConstruct: 'mathFlowMeta'},
+      {
+        character: '$',
+        after: single ? undefined : '\\$',
+        inConstruct: 'phrasing'
+      },
+      {character: '$', inConstruct: 'mathFlowMeta'},
       {atBreak: true, character: '$', after: '\\$'}
     ],
     handlers: {math, inlineMath}
@@ -176,21 +185,24 @@ export function mathToMarkdown(options = {}) {
    * @type {ToMarkdownHandle}
    * @param {Math} node
    */
+  // To do: next major: rename `context` to state, `safeOptions` to info.
+  // Note: fixing this code? Please also fix the similar code for code:
+  // <https://github.com/syntax-tree/mdast-util-to-markdown/blob/main/lib/handle/code.js>
   function math(node, _, context, safeOptions) {
     const raw = node.value || ''
+    const tracker = track(safeOptions)
     const sequence = '$'.repeat(Math.max(longestStreak(raw, '$') + 1, 2))
     const exit = context.enter('mathFlow')
-    const tracker = track(safeOptions)
     let value = tracker.move(sequence)
 
     if (node.meta) {
       const subexit = context.enter('mathFlowMeta')
       value += tracker.move(
         safe(context, node.meta, {
-          ...tracker.current(),
           before: value,
-          after: ' ',
-          encode: ['$']
+          after: '\n',
+          encode: ['$'],
+          ...tracker.current()
         })
       )
       subexit()
@@ -211,10 +223,14 @@ export function mathToMarkdown(options = {}) {
    * @type {ToMarkdownHandle}
    * @param {InlineMath} node
    */
-  function inlineMath(node) {
-    const value = node.value || ''
+  // Note: fixing this code? Please also fix the similar code for inline code:
+  // <https://github.com/syntax-tree/mdast-util-to-markdown/blob/main/lib/handle/inline-code.js>
+  //
+  // To do: next major: rename `context` to state.
+  // To do: next major: use `state` (`safe`, `track`, `patternCompile`).
+  function inlineMath(node, _, context) {
+    let value = node.value || ''
     let size = 1
-    let pad = ''
 
     if (!single) size++
 
@@ -227,21 +243,63 @@ export function mathToMarkdown(options = {}) {
       size++
     }
 
-    // If this is not just spaces or eols (tabs don’t count), and either the first
-    // or last character are a space, eol, or dollar sign, then pad with spaces.
+    const sequence = '$'.repeat(size)
+
+    // If this is not just spaces or eols (tabs don’t count), and either the
+    // first and last character are a space or eol, or the first or last
+    // character are dollar signs, then pad with spaces.
     if (
+      // Contains non-space.
       /[^ \r\n]/.test(value) &&
-      (/[ \r\n$]/.test(value.charAt(0)) ||
-        /[ \r\n$]/.test(value.charAt(value.length - 1)))
+      // Starts with space and ends with space.
+      ((/^[ \r\n]/.test(value) && /[ \r\n]$/.test(value)) ||
+        // Starts or ends with dollar.
+        /^\$|\$$/.test(value))
     ) {
-      pad = ' '
+      value = ' ' + value + ' '
     }
 
-    const sequence = '$'.repeat(size)
-    return sequence + pad + value + pad + sequence
+    let index = -1
+
+    // We have a potential problem: certain characters after eols could result in
+    // blocks being seen.
+    // For example, if someone injected the string `'\n# b'`, then that would
+    // result in an ATX heading.
+    // We can’t escape characters in `inlineMath`, but because eols are
+    // transformed to spaces when going from markdown to HTML anyway, we can swap
+    // them out.
+    while (++index < context.unsafe.length) {
+      const pattern = context.unsafe[index]
+      const expression = patternCompile(pattern)
+      /** @type {RegExpExecArray | null} */
+      let match
+
+      // Only look for `atBreak`s.
+      // Btw: note that `atBreak` patterns will always start the regex at LF or
+      // CR.
+      if (!pattern.atBreak) continue
+
+      while ((match = expression.exec(value))) {
+        let position = match.index
+
+        // Support CRLF (patterns only look for one of the characters).
+        if (
+          value.codePointAt(position) === 10 /* `\n` */ &&
+          value.codePointAt(position - 1) === 13 /* `\r` */
+        ) {
+          position--
+        }
+
+        value = value.slice(0, position) + ' ' + value.slice(match.index + 1)
+      }
+    }
+
+    return sequence + value + sequence
   }
 
-  /** @type {ToMarkdownHandle} */
+  /**
+   * @returns {string}
+   */
   function inlineMathPeek() {
     return '$'
   }

readme.md

@@ -167,6 +167,7 @@ Configuration (optional).
 
 Whether to support text math (inline) with a single dollar (`boolean`, default:
 `true`).
+
 Single dollars work in Pandoc and many other places, but often interfere with
 “normal” dollars in text.
 

test.js

@@ -190,6 +190,33 @@ test('mdast -> markdown', (t) => {
     'should serialize math (text) w/ padding when starting in a dollar sign'
   )
 
+  t.equal(
+    toMarkdown(
+      {type: 'inlineMath', value: ' a '},
+      {extensions: [mathToMarkdown()]}
+    ),
+    '$  a  $\n',
+    'should pad w/ a space if the value starts and ends w/ a space'
+  )
+
+  t.equal(
+    toMarkdown(
+      {type: 'inlineMath', value: ' a'},
+      {extensions: [mathToMarkdown()]}
+    ),
+    '$ a$\n',
+    'should not pad w/ spaces if the value ends w/ a non-space'
+  )
+
+  t.equal(
+    toMarkdown(
+      {type: 'inlineMath', value: 'a '},
+      {extensions: [mathToMarkdown()]}
+    ),
+    '$a $\n',
+    'should not pad w/ spaces if the value starts w/ a non-space'
+  )
+
   t.deepEqual(
     toMarkdown({type: 'math', value: 'a'}, {extensions: [mathToMarkdown()]}),
     '$$\na\n$$\n',
@@ -286,7 +313,7 @@ test('mdast -> markdown', (t) => {
       {type: 'math', meta: 'a\rb\nc', value: ''},
       {extensions: [mathToMarkdown()]}
     ),
-    '$$a
b\nc\n$$\n',
+    '$$a
b
c\n$$\n',
     'should escape `\\r`, `\\n` when in `meta` of math (flow)'
   )
 
@@ -299,5 +326,50 @@ test('mdast -> markdown', (t) => {
     'should escape `$` when in `meta` of math (flow)'
   )
 
+  t.equal(
+    toMarkdown(
+      {type: 'inlineMath', value: 'a\n- b'},
+      {extensions: [mathToMarkdown()]}
+    ),
+    '$a - b$\n',
+    'should prevent breaking out of code (-)'
+  )
+
+  t.equal(
+    toMarkdown(
+      {type: 'inlineMath', value: 'a\n#'},
+      {extensions: [mathToMarkdown()]}
+    ),
+    '$a #$\n',
+    'should prevent breaking out of code (#)'
+  )
+
+  t.equal(
+    toMarkdown(
+      {type: 'inlineMath', value: 'a\n1. '},
+      {extensions: [mathToMarkdown()]}
+    ),
+    '$a 1. $\n',
+    'should prevent breaking out of code (\\d\\.)'
+  )
+
+  t.equal(
+    toMarkdown(
+      {type: 'inlineMath', value: 'a\r- b'},
+      {extensions: [mathToMarkdown()]}
+    ),
+    '$a - b$\n',
+    'should prevent breaking out of code (cr)'
+  )
+
+  t.equal(
+    toMarkdown(
+      {type: 'inlineMath', value: 'a\r\n- b'},
+      {extensions: [mathToMarkdown()]}
+    ),
+    '$a - b$\n',
+    'should prevent breaking out of code (crlf)'
+  )
+
   t.end()
 })