Reimplement MD051/link-fragments using micromark tokens, report reference link issues for definition and fix when possible, handle reporting multiple violations on the same line better.

Author: DavidAnson

.eslintrc.json

@@ -223,6 +223,7 @@
     "unicorn/no-new-array": "off",
     "unicorn/no-null": "off",
     "unicorn/no-unsafe-regex": "off",
+    "unicorn/no-useless-undefined": "off",
     "unicorn/prefer-at": "off",
     "unicorn/prefer-module": "off",
     "unicorn/prefer-string-replace-all": "off",

demo/markdownlint-browser.js

@@ -26,8 +26,8 @@ letters, numbers, `-`, and `_`):
 [Link](#custom-name)
 ```
 
-Alternatively, an HTML `a` tag with an `id` or a `name` attribute can be used to
-define a fragment:
+Alternatively, any HTML tag with an `id` attribute or an `a` tag with a `name`
+attribute can be used to define a fragment:
 
 ```markdown
 <a id="bookmark"></a>

doc-build/md051.md

@@ -2176,8 +2176,8 @@ letters, numbers, `-`, and `_`):
 [Link](#custom-name)
 ```
 
-Alternatively, an HTML `a` tag with an `id` or a `name` attribute can be used to
-define a fragment:
+Alternatively, any HTML tag with an `id` attribute or an `a` tag with a `name`
+attribute can be used to define a fragment:
 
 ```markdown
 <a id="bookmark"></a>

doc/Rules.md

@@ -34,8 +34,8 @@ letters, numbers, `-`, and `_`):
 [Link](#custom-name)
 ```
 
-Alternatively, an HTML `a` tag with an `id` or a `name` attribute can be used to
-define a fragment:
+Alternatively, any HTML tag with an `id` attribute or an `a` tag with a `name`
+attribute can be used to define a fragment:
 
 ```markdown
 <a id="bookmark"></a>

doc/md051.md

@@ -18,10 +18,6 @@ const inlineCommentStartRe =
   /(<!--\s*markdownlint-(disable|enable|capture|restore|disable-file|enable-file|disable-line|disable-next-line|configure-file))(?:\s|-->)/gi;
 module.exports.inlineCommentStartRe = inlineCommentStartRe;
 
-// Regular expression for matching HTML elements
-const htmlElementRe = /<(([A-Za-z][A-Za-z\d-]*)(?:\s[^`>]*)?)\/?>/g;
-module.exports.htmlElementRe = htmlElementRe;
-
 // Regular expressions for range matching
 module.exports.listItemMarkerRe = /^([\s>]*)(?:[*+-]|\d+[.)])\s+/;
 module.exports.orderedListItemMarkerRe = /^[\s>]*0*(\d+)[.)]/;
@@ -444,23 +440,6 @@ module.exports.flattenLists = function flattenLists(tokens) {
   return flattenedLists;
 };
 
-/**
- * Calls the provided function for each specified inline child token.
- *
- * @param {Object} params RuleParams instance.
- * @param {string} type Token type identifier.
- * @param {Function} handler Callback function.
- * @returns {void}
- */
-function forEachInlineChild(params, type, handler) {
-  filterTokens(params, "inline", (token) => {
-    for (const child of token.children.filter((c) => c.type === type)) {
-      handler(child, token);
-    }
-  });
-}
-module.exports.forEachInlineChild = forEachInlineChild;
-
 // Calls the provided function for each heading's content
 module.exports.forEachHeading = function forEachHeading(params, handler) {
   let heading = null;

helpers/helpers.js

@@ -204,6 +204,30 @@ function filterByTypes(tokens, allowed) {
   );
 }
 
+/**
+ * Filter a list of Micromark tokens for HTML tokens.
+ *
+ * @param {Token[]} tokens Micromark tokens.
+ * @returns {Token[]} Filtered tokens.
+ */
+function filterByHtmlTokens(tokens) {
+  const result = [];
+  const pending = [ tokens ];
+  let current = null;
+  while ((current = pending.shift())) {
+    for (const token of filterByTypes(current, [ "htmlFlow", "htmlText" ])) {
+      if (token.type === "htmlText") {
+        result.push(token);
+      } else {
+        // token.type === "htmlFlow"
+        // @ts-ignore
+        pending.push(token.htmlFlowChildren);
+      }
+    }
+  }
+  return result;
+}
+
 /**
  * Returns a list of all nested child tokens.
  *
@@ -293,6 +317,7 @@ function tokenIfType(token, type) {
 
 module.exports = {
   "parse": micromarkParse,
+  filterByHtmlTokens,
   filterByPredicate,
   filterByTypes,
   flattenedChildren,

helpers/micromark.cjs

@@ -3,7 +3,8 @@
 "use strict";
 
 const { addError } = require("../helpers");
-const { filterByTypes, getHtmlTagInfo } = require("../helpers/micromark.cjs");
+const { filterByHtmlTokens, getHtmlTagInfo } =
+  require("../helpers/micromark.cjs");
 
 const nextLinesRe = /[\r\n][\s\S]*$/;
 
@@ -15,34 +16,24 @@ module.exports = {
     let allowedElements = params.config.allowed_elements;
     allowedElements = Array.isArray(allowedElements) ? allowedElements : [];
     allowedElements = allowedElements.map((element) => element.toLowerCase());
-    const pending = [ params.parsers.micromark.tokens ];
-    let current = null;
-    while ((current = pending.shift())) {
-      const tokens = current;
-      for (const token of filterByTypes(tokens, [ "htmlFlow", "htmlText" ])) {
-        if (token.type === "htmlText") {
-          const htmlTagInfo = getHtmlTagInfo(token);
-          if (
-            htmlTagInfo &&
-            !htmlTagInfo.close &&
-            !allowedElements.includes(htmlTagInfo.name.toLowerCase())
-          ) {
-            const range = [
-              token.startColumn,
-              token.text.replace(nextLinesRe, "").length
-            ];
-            addError(
-              onError,
-              token.startLine,
-              "Element: " + htmlTagInfo.name,
-              undefined,
-              range
-            );
-          }
-        } else {
-          // token.type === "htmlFlow"
-          pending.push(token.htmlFlowChildren);
-        }
+    for (const token of filterByHtmlTokens(params.parsers.micromark.tokens)) {
+      const htmlTagInfo = getHtmlTagInfo(token);
+      if (
+        htmlTagInfo &&
+        !htmlTagInfo.close &&
+        !allowedElements.includes(htmlTagInfo.name.toLowerCase())
+      ) {
+        const range = [
+          token.startColumn,
+          token.text.replace(nextLinesRe, "").length
+        ];
+        addError(
+          onError,
+          token.startLine,
+          "Element: " + htmlTagInfo.name,
+          undefined,
+          range
+        );
       }
     }
   }

lib/md033.js

@@ -2,8 +2,9 @@
 
 "use strict";
 
-const { addError, addErrorDetailIf, escapeForRegExp, filterTokens,
-  forEachInlineChild, forEachHeading, htmlElementRe } = require("../helpers");
+const { addError, addErrorDetailIf } = require("../helpers");
+const { filterByHtmlTokens, filterByTypes, getHtmlTagInfo } =
+  require("../helpers/micromark.cjs");
 
 // Regular expression for identifying HTML anchor names
 const idRe = /\sid\s*=\s*['"]?([^'"\s>]+)/iu;
@@ -14,14 +15,14 @@ const anchorRe = /\{(#[a-z\d]+(?:[-_][a-z\d]+)*)\}/gu;
  * Converts a Markdown heading into an HTML fragment according to the rules
  * used by GitHub.
  *
- * @param {Object} inline Inline token for heading.
+ * @param {Object} headingText Heading text token.
  * @returns {string} Fragment string for heading.
  */
-function convertHeadingToHTMLFragment(inline) {
-  const inlineText = inline.children
-    .filter((token) => token.type !== "html_inline")
-    .map((token) => token.content)
-    .join("");
+function convertHeadingToHTMLFragment(headingText) {
+  const inlineText =
+    filterByTypes(headingText.children, [ "codeTextData", "data" ])
+      .map((token) => token.text)
+      .join("");
   return "#" + encodeURIComponent(
     inlineText
       .toLowerCase()
@@ -42,86 +43,96 @@ module.exports = {
   "description": "Link fragments should be valid",
   "tags": [ "links" ],
   "function": function MD051(params, onError) {
+    const { tokens } = params.parsers.micromark;
     const fragments = new Map();
+
     // Process headings
-    forEachHeading(params, (heading, content, inline) => {
-      const fragment = convertHeadingToHTMLFragment(inline);
+    const headingTexts = filterByTypes(
+      tokens,
+      [ "atxHeadingText", "setextHeadingText" ]
+    );
+    for (const headingText of headingTexts) {
+      const fragment = convertHeadingToHTMLFragment(headingText);
       const count = fragments.get(fragment) || 0;
       if (count) {
         fragments.set(`${fragment}-${count}`, 0);
       }
       fragments.set(fragment, count + 1);
       let match = null;
-      while ((match = anchorRe.exec(content)) !== null) {
+      while ((match = anchorRe.exec(headingText.text)) !== null) {
         const [ , anchor ] = match;
         if (!fragments.has(anchor)) {
           fragments.set(anchor, 1);
         }
       }
-    });
+    }
+
     // Process HTML anchors
-    const processHtmlToken = (token) => {
-      let match = null;
-      while ((match = htmlElementRe.exec(token.content)) !== null) {
-        const [ tag, , element ] = match;
-        const anchorMatch = idRe.exec(tag) ||
-            (element.toLowerCase() === "a" && nameRe.exec(tag));
+    for (const token of filterByHtmlTokens(tokens)) {
+      const htmlTagInfo = getHtmlTagInfo(token);
+      if (htmlTagInfo && !htmlTagInfo.close) {
+        const anchorMatch = idRe.exec(token.text) ||
+          (htmlTagInfo.name.toLowerCase() === "a" && nameRe.exec(token.text));
         if (anchorMatch) {
           fragments.set(`#${anchorMatch[1]}`, 0);
         }
       }
-    };
-    filterTokens(params, "html_block", processHtmlToken);
-    forEachInlineChild(params, "html_inline", processHtmlToken);
-    // Process link fragments
-    forEachInlineChild(params, "link_open", (token) => {
-      const { attrs, lineNumber, line } = token;
-      const href = attrs.find((attr) => attr[0] === "href");
-      const id = href && href[1];
-      if (id && (id.length > 1) && (id[0] === "#") && !fragments.has(id)) {
-        let context = id;
-        let range = null;
-        let fixInfo = null;
-        const match = line.match(
-          new RegExp(`\\[.*?\\]\\(${escapeForRegExp(context)}\\)`)
-        );
-        if (match) {
-          [ context ] = match;
-          const index = match.index;
-          const length = context.length;
-          range = [ index + 1, length ];
-          fixInfo = {
-            "editColumn": index + (length - id.length),
-            "deleteCount": id.length,
-            "insertText": null
-          };
-        }
-        const idLower = id.toLowerCase();
-        const mixedCaseKey = [ ...fragments.keys() ]
-          .find((key) => idLower === key.toLowerCase());
-        if (mixedCaseKey) {
-          (fixInfo || {}).insertText = mixedCaseKey;
-          addErrorDetailIf(
-            onError,
-            lineNumber,
-            mixedCaseKey,
-            id,
-            undefined,
-            context,
-            range,
-            fixInfo
-          );
-        } else {
-          addError(
-            onError,
-            lineNumber,
-            undefined,
-            context,
-            // @ts-ignore
-            range
-          );
+    }
+
+    // Process link and definition fragments
+    const parentChilds = [
+      [ "link", "resourceDestinationString" ],
+      [ "definition", "definitionDestinationString" ]
+    ];
+    for (const [ parentType, definitionType ] of parentChilds) {
+      const links = filterByTypes(tokens, [ parentType ]);
+      for (const link of links) {
+        const definitions = filterByTypes(link.children, [ definitionType ]);
+        for (const definition of definitions) {
+          if (
+            (definition.text.length > 1) &&
+            definition.text.startsWith("#") &&
+            !fragments.has(definition.text)
+          ) {
+            // eslint-disable-next-line no-undef-init
+            let range = undefined;
+            // eslint-disable-next-line no-undef-init
+            let fixInfo = undefined;
+            if (link.startLine === link.endLine) {
+              range = [ link.startColumn, link.endColumn - link.startColumn ];
+              fixInfo = {
+                "editColumn": definition.startColumn,
+                "deleteCount": definition.endColumn - definition.startColumn
+              };
+            }
+            const definitionTextLower = definition.text.toLowerCase();
+            const mixedCaseKey = [ ...fragments.keys() ]
+              .find((key) => definitionTextLower === key.toLowerCase());
+            if (mixedCaseKey) {
+              // @ts-ignore
+              (fixInfo || {}).insertText = mixedCaseKey;
+              addErrorDetailIf(
+                onError,
+                link.startLine,
+                mixedCaseKey,
+                definition.text,
+                undefined,
+                link.text,
+                range,
+                fixInfo
+              );
+            } else {
+              addError(
+                onError,
+                link.startLine,
+                undefined,
+                link.text,
+                range
+              );
+            }
+          }
         }
       }
-    });
+    }
   }
 };