markdownlint 0.27.0 → 0.28.0

package/doc/CustomRules.md

@@ -34,7 +34,7 @@ module.exports = {
   "information": new URL("https://example.com/rules/any-blockquote"),
   "tags": [ "test" ],
   "function": function rule(params, onError) {
-    params.tokens.filter(function filterToken(token) {
+    params.parsers.markdownit.tokens.filter(function filterToken(token) {
       return token.type === "blockquote_open";
     }).forEach(function forToken(blockquote) {
       var lines = blockquote.map[1] - blockquote.map[0];
@@ -120,8 +120,6 @@ exception.
 - [Code for all `markdownlint` built-in rules][lib]
 - [Package configuration for publishing to npm][test-rules-npm]
   - Packages should export a single rule object or an `Array` of rule objects
-- [Custom rules from the Microsoft/vscode-docs-authoring
-  repository][vscode-docs-authoring]
 - [Custom rules from the axibase/docs-util repository][docs-util]
 - [Custom rules from the webhintio/hint repository][hint]
 
@@ -374,4 +372,3 @@ Yields the `params` object:
 [options-custom-rules]: ../README.md#optionscustomrules
 [test-rules]: ../test/rules
 [test-rules-npm]: ../test/rules/npm
-[vscode-docs-authoring]: https://github.com/microsoft/vscode-docs-authoring/tree/main/packages/docs-linting/markdownlint-custom-rules

package/doc/Rules.md

@@ -1410,42 +1410,48 @@ Aliases: `no-bare-urls`
 
 Fixable: Some violations can be fixed by tooling
 
-This rule is triggered whenever a URL is given that isn't surrounded by angle
-brackets:
+This rule is triggered whenever a URL or email address appears without
+surrounding angle brackets:
 
 ```markdown
-For more information, see https://www.example.com/.
+For more info, visit https://www.example.com/ or email user@example.com.
 ```
 
-To fix this, add angle brackets around the URL:
+To fix this, add angle brackets around the URL or email address:
 
 ```markdown
-For more information, see <https://www.example.com/>.
+For more info, visit <https://www.example.com/> or email <user@example.com>.
 ```
 
-Note: To use a bare URL without it being converted into a link, enclose it in
-a code block, otherwise in some Markdown parsers it *will* be converted:
+Note: To include a bare URL or email without it being converted into a link,
+wrap it in a code span:
 
 ```markdown
-`https://www.example.com`
+Not a clickable link: `https://www.example.com`
 ```
 
-Note: The following scenario does *not* trigger this rule to avoid conflicts
-with `MD011`/`no-reversed-links`:
+Note: The following scenario does not trigger this rule because it could be a
+shortcut link:
 
 ```markdown
 [https://www.example.com]
 ```
 
-The use of quotes around a bare link will *not* trigger this rule, either:
+Note: The following syntax triggers this rule because the nested link could be
+a shortcut link (which takes precedence):
 
 ```markdown
-"https://www.example.com"
-'https://www.example.com'
+[text [shortcut] text](https://example.com)
 ```
 
-Rationale: Without angle brackets, the URL isn't converted into a link by many
-Markdown parsers.
+To avoid this, escape both inner brackets:
+
+```markdown
+[link \[text\] link](https://example.com)
+```
+
+Rationale: Without angle brackets, a bare URL or email isn't converted into a
+link by some Markdown parsers.
 
 <a name="md035"></a>
 
@@ -2184,7 +2190,7 @@ convert heading to lowercase, remove punctuation, convert spaces to dashes,
 append an incrementing integer as needed for uniqueness.
 
 [github-section-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links
-[github-heading-algorithm]: https://github.com/gjtorikian/html-pipeline/blob/main/lib/html/pipeline/toc_filter.rb
+[github-heading-algorithm]: https://github.com/gjtorikian/html-pipeline/blob/f13a1534cb650ba17af400d1acd3a22c28004c09/lib/html/pipeline/toc_filter.rb
 
 <a name="md052"></a>
 

package/doc/md034.md

@@ -6,39 +6,45 @@ Aliases: `no-bare-urls`
 
 Fixable: Some violations can be fixed by tooling
 
-This rule is triggered whenever a URL is given that isn't surrounded by angle
-brackets:
+This rule is triggered whenever a URL or email address appears without
+surrounding angle brackets:
 
 ```markdown
-For more information, see https://www.example.com/.
+For more info, visit https://www.example.com/ or email user@example.com.
 ```
 
-To fix this, add angle brackets around the URL:
+To fix this, add angle brackets around the URL or email address:
 
 ```markdown
-For more information, see <https://www.example.com/>.
+For more info, visit <https://www.example.com/> or email <user@example.com>.
 ```
 
-Note: To use a bare URL without it being converted into a link, enclose it in
-a code block, otherwise in some Markdown parsers it *will* be converted:
+Note: To include a bare URL or email without it being converted into a link,
+wrap it in a code span:
 
 ```markdown
-`https://www.example.com`
+Not a clickable link: `https://www.example.com`
 ```
 
-Note: The following scenario does *not* trigger this rule to avoid conflicts
-with `MD011`/`no-reversed-links`:
+Note: The following scenario does not trigger this rule because it could be a
+shortcut link:
 
 ```markdown
 [https://www.example.com]
 ```
 
-The use of quotes around a bare link will *not* trigger this rule, either:
+Note: The following syntax triggers this rule because the nested link could be
+a shortcut link (which takes precedence):
 
 ```markdown
-"https://www.example.com"
-'https://www.example.com'
+[text [shortcut] text](https://example.com)
 ```
 
-Rationale: Without angle brackets, the URL isn't converted into a link by many
-Markdown parsers.
+To avoid this, escape both inner brackets:
+
+```markdown
+[link \[text\] link](https://example.com)
+```
+
+Rationale: Without angle brackets, a bare URL or email isn't converted into a
+link by some Markdown parsers.

package/doc/md051.md

@@ -47,4 +47,4 @@ convert heading to lowercase, remove punctuation, convert spaces to dashes,
 append an incrementing integer as needed for uniqueness.
 
 [github-section-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links
-[github-heading-algorithm]: https://github.com/gjtorikian/html-pipeline/blob/main/lib/html/pipeline/toc_filter.rb
+[github-heading-algorithm]: https://github.com/gjtorikian/html-pipeline/blob/f13a1534cb650ba17af400d1acd3a22c28004c09/lib/html/pipeline/toc_filter.rb

package/helpers/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2022 David Anson
+Copyright (c) David Anson
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/helpers/helpers.js

@@ -2,6 +2,8 @@
 
 "use strict";
 
+const micromark = require("./micromark.cjs");
+
 // Regular expression for matching common newline characters
 // See NEWLINES_RE in markdown-it/lib/rules_core/normalize.js
 const newLineRe = /\r\n?|\n/g;
@@ -33,10 +35,6 @@ const emphasisMarkersRe = /[_*]/g;
 const blockquotePrefixRe = /^[>\s]*/;
 module.exports.blockquotePrefixRe = blockquotePrefixRe;
 
-// Regular expression for reference links (full, collapsed, and shortcut)
-const referenceLinkRe =
-  /!?\\?\[((?:\[[^\]\0]*\]|[^[\]\0])*)\](?:\[([^\]\0]*)\]|([^(])|$)/g;
-
 // Regular expression for link reference definitions
 const linkReferenceDefinitionRe = /^ {0,3}\[([^\]]*[^\\])\]:/;
 module.exports.linkReferenceDefinitionRe = linkReferenceDefinitionRe;
@@ -193,19 +191,6 @@ module.exports.escapeForRegExp = function escapeForRegExp(str) {
   return str.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
 };
 
-// Un-escapes Markdown content (simple algorithm; not a parser)
-const escapedMarkdownRe = /\\./g;
-module.exports.unescapeMarkdown =
-  function unescapeMarkdown(markdown, replacement) {
-    return markdown.replace(escapedMarkdownRe, (match) => {
-      const char = match[1];
-      if ("!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~".includes(char)) {
-        return replacement || char;
-      }
-      return match;
-    });
-  };
-
 /**
  * Return the string representation of a fence markup character.
  *
@@ -288,7 +273,7 @@ module.exports.unorderedListStyleFor = function unorderedListStyleFor(token) {
  * @returns {void}
  */
 function filterTokens(params, type, handler) {
-  for (const token of params.tokens) {
+  for (const token of params.parsers.markdownit.tokens) {
     if (token.type === type) {
       handler(token);
     }
@@ -343,7 +328,7 @@ module.exports.getLineMetadata = function getLineMetadata(params) {
   filterTokens(params, "hr", (token) => {
     lineMetadata[token.map[0]][6] = true;
   });
-  for (const token of params.tokens.filter(isMathBlock)) {
+  for (const token of params.parsers.markdownit.tokens.filter(isMathBlock)) {
     for (let i = token.map[0]; i < token.map[1]; i++) {
       lineMetadata[i][7] = true;
     }
@@ -437,7 +422,7 @@ module.exports.forEachInlineChild = forEachInlineChild;
 // Calls the provided function for each heading's content
 module.exports.forEachHeading = function forEachHeading(params, handler) {
   let heading = null;
-  for (const token of params.tokens) {
+  for (const token of params.parsers.markdownit.tokens) {
     if (token.type === "heading_open") {
       heading = token;
     } else if (token.type === "heading_close") {
@@ -818,137 +803,117 @@ module.exports.emphasisMarkersInContent = emphasisMarkersInContent;
 /**
  * Returns an object with information about reference links and images.
  *
- * @param {Object} lineMetadata Line metadata object.
+ * @param {Object} params RuleParams instance.
  * @returns {Object} Reference link/image data.
  */
-function getReferenceLinkImageData(lineMetadata) {
-  // Initialize return values
-  const references = new Map();
-  const shortcuts = new Map();
+function getReferenceLinkImageData(params) {
+  const normalizeReference = (s) => s.toLowerCase().trim().replace(/\s+/g, " ");
   const definitions = new Map();
-  const duplicateDefinitions = [];
   const definitionLineIndices = [];
-  // Define helper functions
-  const normalizeLabel = (s) => s.toLowerCase().trim().replace(/\s+/g, " ");
-  const exclusions = [];
-  const excluded = (match) => withinAnyRange(
-    exclusions, 0, match.index, match[0].length - (match[3] || "").length
-  );
-  // Convert input to single-line so multi-line links/images are easier
-  const lineOffsets = [];
-  let currentOffset = 0;
-  const contentLines = [];
-  forEachLine(lineMetadata, (line, lineIndex, inCode) => {
-    lineOffsets[lineIndex] = currentOffset;
-    if (!inCode) {
-      line = line.replace(blockquotePrefixRe, "");
-      if (line.trim().length === 0) {
-        // Allow RegExp to detect the end of a block
-        line = "\0";
-      }
-      contentLines.push(line);
-      currentOffset += line.length + 1;
-    }
-  });
-  lineOffsets.push(currentOffset);
-  const contentLine = contentLines.join(" ");
-  // Determine single-line exclusions for inline code spans
-  forEachInlineCodeSpan(contentLine, (code, lineIndex, columnIndex) => {
-    exclusions.push([ 0, columnIndex, code.length ]);
-  });
-  // Identify all link/image reference definitions
-  forEachLine(lineMetadata, (line, lineIndex, inCode) => {
-    if (!inCode) {
-      const linkReferenceDefinitionMatch = linkReferenceDefinitionRe.exec(line);
-      if (linkReferenceDefinitionMatch) {
-        const label = normalizeLabel(linkReferenceDefinitionMatch[1]);
-        if (definitions.has(label)) {
-          duplicateDefinitions.push([ label, lineIndex ]);
-        } else {
-          definitions.set(label, lineIndex);
-        }
-        const labelLength = linkReferenceDefinitionMatch[0].length;
-        exclusions.push([ 0, lineOffsets[lineIndex], labelLength ]);
-        const hasDefinition = line.slice(labelLength).trim().length > 0;
-        definitionLineIndices.push(lineIndex);
-        if (!hasDefinition) {
-          definitionLineIndices.push(lineIndex + 1);
+  const duplicateDefinitions = [];
+  const references = new Map();
+  const shortcuts = new Map();
+  const filteredTokens =
+    micromark.filterByTypes(
+      params.parsers.micromark.tokens,
+      [
+        // definitionLineIndices
+        "definition", "gfmFootnoteDefinition",
+        // definitions and definitionLineIndices
+        "definitionLabelString", "gfmFootnoteDefinitionLabelString",
+        // references and shortcuts
+        "gfmFootnoteCall", "image", "link"
+      ]
+    );
+  for (const token of filteredTokens) {
+    let labelPrefix = "";
+    // eslint-disable-next-line default-case
+    switch (token.type) {
+      case "definition":
+      case "gfmFootnoteDefinition":
+        // definitionLineIndices
+        for (let i = token.startLine; i <= token.endLine; i++) {
+          definitionLineIndices.push(i - 1);
         }
-      }
-    }
-  });
-  // Identify all link and image references
-  let lineIndex = 0;
-  const pendingContents = [
-    {
-      "content": contentLine,
-      "contentLineIndex": 0,
-      "contentIndex": 0,
-      "topLevel": true
-    }
-  ];
-  let pendingContent = null;
-  while ((pendingContent = pendingContents.shift())) {
-    const { content, contentLineIndex, contentIndex, topLevel } =
-      pendingContent;
-    let referenceLinkMatch = null;
-    while ((referenceLinkMatch = referenceLinkRe.exec(content)) !== null) {
-      const [ matchString, matchText, matchLabel ] = referenceLinkMatch;
-      if (
-        !matchString.startsWith("\\") &&
-        !matchString.startsWith("!\\") &&
-        !matchText.endsWith("\\") &&
-        !(matchLabel || "").endsWith("\\") &&
-        !(topLevel && excluded(referenceLinkMatch))
-      ) {
-        const shortcutLink = (matchLabel === undefined);
-        const collapsedLink =
-          (!shortcutLink && (matchLabel.length === 0));
-        const label = normalizeLabel(
-          (shortcutLink || collapsedLink) ? matchText : matchLabel
-        );
-        if (label.length > 0) {
-          const referenceindex = referenceLinkMatch.index;
-          if (topLevel) {
-            // Calculate line index
-            while (lineOffsets[lineIndex + 1] <= referenceindex) {
-              lineIndex++;
-            }
+        break;
+      case "gfmFootnoteDefinitionLabelString":
+        labelPrefix = "^";
+      case "definitionLabelString": // eslint-disable-line no-fallthrough
+        {
+          // definitions and definitionLineIndices
+          const reference = normalizeReference(`${labelPrefix}${token.text}`);
+          if (definitions.has(reference)) {
+            duplicateDefinitions.push([ reference, token.startLine - 1 ]);
           } else {
-            // Use provided line index
-            lineIndex = contentLineIndex;
+            definitions.set(reference, token.startLine - 1);
           }
-          const referenceIndex = referenceindex +
-            (topLevel ? -lineOffsets[lineIndex] : contentIndex);
-          const referenceDatum = [
-            lineIndex,
-            referenceIndex,
-            matchString.length,
-            matchText.length,
-            (matchLabel || "").length
-          ];
-          if (shortcutLink) {
-            // Track separately due to ambiguity in "text [text] text"
-            const shortcutData = shortcuts.get(label) || [];
-            shortcutData.push(referenceDatum);
-            shortcuts.set(label, shortcutData);
-          } else {
-            // Track reference and location
-            const referenceData = references.get(label) || [];
-            referenceData.push(referenceDatum);
-            references.set(label, referenceData);
+        }
+        break;
+      case "gfmFootnoteCall":
+      case "image":
+      case "link":
+        {
+          let isShortcut = false;
+          let isFullOrCollapsed = false;
+          let labelText = null;
+          let referenceStringText = null;
+          const shortcutCandidate =
+            micromark.matchAndGetTokensByType(token.children, [ "label" ]);
+          if (shortcutCandidate) {
+            labelText =
+              micromark.getTokenTextByType(
+                shortcutCandidate[0].children, "labelText"
+              );
+            isShortcut = (labelText !== null);
           }
-          // Check for links embedded in brackets
-          if (!matchString.startsWith("!")) {
-            pendingContents.push({
-              "content": matchText,
-              "contentLineIndex": lineIndex,
-              "contentIndex": referenceIndex + 1,
-              "topLevel": false
-            });
+          const fullAndCollapsedCandidate =
+            micromark.matchAndGetTokensByType(
+              token.children, [ "label", "reference" ]
+            );
+          if (fullAndCollapsedCandidate) {
+            labelText =
+              micromark.getTokenTextByType(
+                fullAndCollapsedCandidate[0].children, "labelText"
+              );
+            referenceStringText =
+              micromark.getTokenTextByType(
+                fullAndCollapsedCandidate[1].children, "referenceString"
+              );
+            isFullOrCollapsed = (labelText !== null);
+          }
+          const footnote = micromark.matchAndGetTokensByType(
+            token.children,
+            [
+              "gfmFootnoteCallLabelMarker", "gfmFootnoteCallMarker",
+              "gfmFootnoteCallString", "gfmFootnoteCallLabelMarker"
+            ],
+            [ "gfmFootnoteCallMarker", "gfmFootnoteCallString" ]
+          );
+          if (footnote) {
+            const callMarkerText = footnote[0].text;
+            const callString = footnote[1].text;
+            labelText = `${callMarkerText}${callString}`;
+            isShortcut = true;
+          }
+          // Track shortcuts separately due to ambiguity in "text [text] text"
+          if (isShortcut || isFullOrCollapsed) {
+            const referenceDatum = [
+              token.startLine - 1,
+              token.startColumn - 1,
+              token.text.length,
+              // @ts-ignore
+              labelText.length,
+              (referenceStringText || "").length
+            ];
+            const reference =
+              normalizeReference(referenceStringText || labelText);
+            const dictionary = isShortcut ? shortcuts : references;
+            const referenceData = dictionary.get(reference) || [];
+            referenceData.push(referenceDatum);
+            dictionary.set(reference, referenceData);
           }
         }
-      }
+        break;
     }
   }
   return {
@@ -1187,110 +1152,3 @@ function expandTildePath(file, os) {
   return homedir ? file.replace(/^~($|\/|\\)/, `${homedir}$1`) : file;
 }
 module.exports.expandTildePath = expandTildePath;
-
-/**
- * RegExp.exec-style implementation of function expressions.
- *
- * @param {Function} funcExp Function that takes string and returns
- * [index, length] or null.
- * @param {string} input String to search.
- * @returns {string[] | null} RegExp.exec-style [match] with an index property.
- */
-function funcExpExec(funcExp, input) {
-  // Start or resume match
-  // @ts-ignore
-  const lastIndex = funcExp.lastIndex || 0;
-  const result = funcExp(input.slice(lastIndex));
-  if (result) {
-    // Update lastIndex and return match
-    const [ subIndex, length ] = result;
-    const index = lastIndex + subIndex;
-    // @ts-ignore
-    funcExp.lastIndex = index + length;
-    const match = [ input.slice(index, index + length) ];
-    // @ts-ignore
-    match.index = index;
-    return match;
-  }
-  // Reset lastIndex and return no match
-  // @ts-ignore
-  funcExp.lastIndex = 0;
-  return null;
-}
-module.exports.funcExpExec = funcExpExec;
-
-const urlFeProtocolRe = /(?:http|ftp)s?:\/\//i;
-const urlFeAutolinkTerminalsRe = / |$/;
-const urlFeBareTerminalsRe = /[ ,!`'"\]]|$/;
-const urlFeNonTerminalsRe = "-#/";
-const urlFePunctuationRe = /\p{Punctuation}/u;
-const urlFePrefixToPostfix = new Map([
-  [ " ", " " ],
-  [ "`", "`" ],
-  [ "'", "'" ],
-  [ "\"", "\"" ],
-  [ "‘", "’" ],
-  [ "“", "”" ],
-  [ "«", "»" ],
-  [ "*", "*" ],
-  [ "_", "_" ],
-  [ "(", ")" ],
-  [ "[", "]" ],
-  [ "{", "}" ],
-  [ "<", ">" ],
-  [ ">", "<" ]
-]);
-
-/**
- * Function expression that matches URLs.
- *
- * @param {string} input Substring to search for a URL.
- * @returns {Array | null} [index, length] of URL or null.
- */
-function urlFe(input) {
-  // Find start of URL by searching for protocol
-  const match = input.match(urlFeProtocolRe);
-  if (match) {
-    // Look for matching pre/postfix characters (ex: <...>)
-    const start = match.index || 0;
-    const length = match[0].length;
-    const prefix = input[start - 1] || " ";
-    const postfix = urlFePrefixToPostfix.get(prefix);
-    // @ts-ignore
-    let endPostfix = input.indexOf(postfix, start + length);
-    if (endPostfix === -1) {
-      endPostfix = input.length;
-    }
-    // Look for characters that terminate a URL
-    const terminalsRe =
-      (prefix === "<") ? urlFeAutolinkTerminalsRe : urlFeBareTerminalsRe;
-    const endTerminal = start + input.slice(start).search(terminalsRe);
-    // Determine tentative end of URL
-    let end = Math.min(endPostfix, endTerminal);
-    if (prefix === " ") {
-      // If the URL used " " as pre/postfix characters, trim the end
-      if (input[end - 1] === ")") {
-        // Trim any ")" beyond the last "(...)" pair
-        const lastOpenParen = input.lastIndexOf("(", end - 2);
-        if (lastOpenParen <= start) {
-          end--;
-        } else {
-          const nextCloseParen = input.indexOf(")", lastOpenParen + 1);
-          end = nextCloseParen + 1;
-        }
-      } else {
-        // Trim unwanted punctuation
-        while (
-          !urlFeNonTerminalsRe.includes(input[end - 1]) &&
-          urlFePunctuationRe.test(input[end - 1])
-        ) {
-          end--;
-        }
-      }
-    }
-    return [ start, end - start ];
-  }
-  // No match
-  return null;
-}
-module.exports.urlFe = urlFe;