tools: avoid unnecessary escaping in markdown formatter

Update mdast-util-to-markdown to 1.2.4 which reduces unnecessary
escaping of `_` and some other characters. Re-run markdown formatter.

PR-URL: https://github.com/nodejs/node/pull/40645
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>

2 files changed, 46 insertions, 17 deletions

diff --git a/tools/lint-md/lint-md.mjs b/tools/lint-md/lint-md.mjs
index 9d3903a1d4b..baecd0a3e2d 100644
--- a/tools/lint-md/lint-md.mjs
+++ b/tools/lint-md/lint-md.mjs
@@ -13579,6 +13579,21 @@ function joinDefaults(left, right, parent, context) {
  * @typedef {import('./types.js').Unsafe} Unsafe
  */
 
+/**
+ * List of constructs that occur in phrasing (paragraphs, headings), but cannot
+ * contain things like attention (emphasis, strong), images, or links.
+ * So they sort of cancel each other out.
+ * Note: could use a better name.
+ */
+const fullPhrasingSpans = [
+  'autolink',
+  'destinationLiteral',
+  'destinationRaw',
+  'reference',
+  'titleQuote',
+  'titleApostrophe'
+];
+
 /** @type {Array.<Unsafe>} */
 const unsafe = [
   {character: '\t', after: '[\\r\\n]', inConstruct: 'phrasing'},
@@ -13617,7 +13632,12 @@ const unsafe = [
   },
   // An exclamation mark can start an image, if it is followed by a link or
   // a link reference.
-  {character: '!', after: '\\[', inConstruct: 'phrasing'},
+  {
+    character: '!',
+    after: '\\[',
+    inConstruct: 'phrasing',
+    notInConstruct: fullPhrasingSpans
+  },
   // A quote can break out of a title.
   {character: '"', inConstruct: 'titleQuote'},
   // A number sign could start an ATX heading if it starts a line.
@@ -13630,14 +13650,20 @@ const unsafe = [
   {character: "'", inConstruct: 'titleApostrophe'},
   // A left paren could break out of a destination raw.
   {character: '(', inConstruct: 'destinationRaw'},
-  {before: '\\]', character: '(', inConstruct: 'phrasing'},
+  // A left paren followed by `]` could make something into a link or image.
+  {
+    before: '\\]',
+    character: '(',
+    inConstruct: 'phrasing',
+    notInConstruct: fullPhrasingSpans
+  },
   // A right paren could start a list item or break out of a destination
   // raw.
   {atBreak: true, before: '\\d+', character: ')'},
   {character: ')', inConstruct: 'destinationRaw'},
   // An asterisk can start thematic breaks, list items, emphasis, strong.
   {atBreak: true, character: '*'},
-  {character: '*', inConstruct: 'phrasing'},
+  {character: '*', inConstruct: 'phrasing', notInConstruct: fullPhrasingSpans},
   // A plus sign could start a list item.
   {atBreak: true, character: '+'},
   // A dash can start thematic breaks, list items, and setext heading
@@ -13652,7 +13678,12 @@ const unsafe = [
   // An autolink also starts with a letter.
   // Finally, it could break out of a destination literal.
   {atBreak: true, character: '<', after: '[!/?A-Za-z]'},
-  {character: '<', after: '[!/?A-Za-z]', inConstruct: 'phrasing'},
+  {
+    character: '<',
+    after: '[!/?A-Za-z]',
+    inConstruct: 'phrasing',
+    notInConstruct: fullPhrasingSpans
+  },
   {character: '<', inConstruct: 'destinationLiteral'},
   // An equals to can start setext heading underlines.
   {atBreak: true, character: '='},
@@ -13663,7 +13694,8 @@ const unsafe = [
   // Question mark and at sign are not used in markdown for constructs.
   // A left bracket can start definitions, references, labels,
   {atBreak: true, character: '['},
-  {character: '[', inConstruct: ['phrasing', 'label', 'reference']},
+  {character: '[', inConstruct: 'phrasing', notInConstruct: fullPhrasingSpans},
+  {character: '[', inConstruct: ['label', 'reference']},
   // A backslash can start an escape (when followed by punctuation) or a
   // hard break (when followed by an eol).
   // Note: typical escapes are handled in `safe`!
@@ -13673,18 +13705,15 @@ const unsafe = [
   // Caret is not used in markdown for constructs.
   // An underscore can start emphasis, strong, or a thematic break.
   {atBreak: true, character: '_'},
-  {character: '_', inConstruct: 'phrasing'},
+  {character: '_', inConstruct: 'phrasing', notInConstruct: fullPhrasingSpans},
   // A grave accent can start code (fenced or text), or it can break out of
   // a grave accent code fence.
   {atBreak: true, character: '`'},
   {
     character: '`',
-    inConstruct: [
-      'codeFencedLangGraveAccent',
-      'codeFencedMetaGraveAccent',
-      'phrasing'
-    ]
+    inConstruct: ['codeFencedLangGraveAccent', 'codeFencedMetaGraveAccent']
   },
+  {character: '`', inConstruct: 'phrasing', notInConstruct: fullPhrasingSpans},
   // Left brace, vertical bar, right brace are not used in markdown for
   // constructs.
   // A tilde can start code (fenced).
diff --git a/tools/lint-md/package-lock.json b/tools/lint-md/package-lock.json
index 75e4ea906e7..59eb027bd9d 100644
--- a/tools/lint-md/package-lock.json
+++ b/tools/lint-md/package-lock.json
@@ -730,9 +730,9 @@
       }
     },
     "node_modules/mdast-util-to-markdown": {
-      "version": "1.2.3",
-      "resolved": "https://registry.npmjs.org/mdast-util-to-markdown/-/mdast-util-to-markdown-1.2.3.tgz",
-      "integrity": "sha512-040jJYtjOUdbvYAXCfPrpLJRdvMOmR33KRqlhT4r+fEbVM+jao1RMbA8RmGeRmw8RAj3vQ+HvhIaJPijvnOwCg==",
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/mdast-util-to-markdown/-/mdast-util-to-markdown-1.2.4.tgz",
+      "integrity": "sha512-Wive3NvrNS4OY5yYKBADdK1QSlbJUZyZ2ssanITUzNQ7sxMfBANTVjLrAA9BFXshaeG9G77xpOK/z+TTret5Hg==",
       "dependencies": {
         "@types/mdast": "^3.0.0",
         "@types/unist": "^2.0.0",
@@ -3139,9 +3139,9 @@
       }
     },
     "mdast-util-to-markdown": {
-      "version": "1.2.3",
-      "resolved": "https://registry.npmjs.org/mdast-util-to-markdown/-/mdast-util-to-markdown-1.2.3.tgz",
-      "integrity": "sha512-040jJYtjOUdbvYAXCfPrpLJRdvMOmR33KRqlhT4r+fEbVM+jao1RMbA8RmGeRmw8RAj3vQ+HvhIaJPijvnOwCg==",
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/mdast-util-to-markdown/-/mdast-util-to-markdown-1.2.4.tgz",
+      "integrity": "sha512-Wive3NvrNS4OY5yYKBADdK1QSlbJUZyZ2ssanITUzNQ7sxMfBANTVjLrAA9BFXshaeG9G77xpOK/z+TTret5Hg==",
       "requires": {
         "@types/mdast": "^3.0.0",
         "@types/unist": "^2.0.0",