markdownlint 0.24.0 → 0.26.0

package/lib/markdownlint.js

@@ -5,6 +5,7 @@
 const path = require("path");
 const { promisify } = require("util");
 const markdownIt = require("markdown-it");
+const { deprecatedRuleNames } = require("./constants");
 const rules = require("./rules");
 const helpers = require("../helpers");
 const cache = require("./cache");
@@ -14,47 +15,46 @@ const cache = require("./cache");
 const dynamicRequire = (typeof __non_webpack_require__ === "undefined") ? require : /* c8 ignore next */ __non_webpack_require__;
 // Capture native require implementation for dynamic loading of modules
 
-const deprecatedRuleNames = [ "MD002", "MD006" ];
-
 /**
  * Validate the list of rules for structure and reuse.
  *
  * @param {Rule[]} ruleList List of rules.
- * @returns {string} Error message if validation fails.
+ * @param {boolean} synchronous Whether to execute synchronously.
+ * @returns {Error | null} Error message if validation fails.
  */
-function validateRuleList(ruleList) {
+function validateRuleList(ruleList, synchronous) {
   let result = null;
   if (ruleList.length === rules.length) {
     // No need to validate if only using built-in rules
     return result;
   }
   const allIds = {};
-  ruleList.forEach(function forRule(rule, index) {
+  for (const [ index, rule ] of ruleList.entries()) {
     const customIndex = index - rules.length;
-    // eslint-disable-next-line jsdoc/require-jsdoc
+    // eslint-disable-next-line no-inner-declarations, jsdoc/require-jsdoc
     function newError(property) {
       return new Error(
         "Property '" + property + "' of custom rule at index " +
         customIndex + " is incorrect.");
     }
-    [ "names", "tags" ].forEach(function forProperty(property) {
+    for (const property of [ "names", "tags" ]) {
       const value = rule[property];
       if (!result &&
         (!value || !Array.isArray(value) || (value.length === 0) ||
          !value.every(helpers.isString) || value.some(helpers.isEmptyString))) {
         result = newError(property);
       }
-    });
-    [
+    }
+    for (const propertyInfo of [
       [ "description", "string" ],
       [ "function", "function" ]
-    ].forEach(function forProperty(propertyInfo) {
+    ]) {
       const property = propertyInfo[0];
       const value = rule[property];
       if (!result && (!value || (typeof value !== propertyInfo[1]))) {
         result = newError(property);
       }
-    });
+    }
     if (
       !result &&
       rule.information &&
@@ -62,25 +62,38 @@ function validateRuleList(ruleList) {
     ) {
       result = newError("information");
     }
+    if (
+      !result &&
+      (rule.asynchronous !== undefined) &&
+      (typeof rule.asynchronous !== "boolean")
+    ) {
+      result = newError("asynchronous");
+    }
+    if (!result && rule.asynchronous && synchronous) {
+      result = new Error(
+        "Custom rule " + rule.names.join("/") + " at index " + customIndex +
+        " is asynchronous and can not be used in a synchronous context."
+      );
+    }
     if (!result) {
-      rule.names.forEach(function forName(name) {
+      for (const name of rule.names) {
         const nameUpper = name.toUpperCase();
         if (!result && (allIds[nameUpper] !== undefined)) {
           result = new Error("Name '" + name + "' of custom rule at index " +
             customIndex + " is already used as a name or tag.");
         }
         allIds[nameUpper] = true;
-      });
-      rule.tags.forEach(function forTag(tag) {
+      }
+      for (const tag of rule.tags) {
         const tagUpper = tag.toUpperCase();
         if (!result && allIds[tagUpper]) {
           result = new Error("Tag '" + tag + "' of custom rule at index " +
             customIndex + " is already used as a name.");
         }
         allIds[tagUpper] = false;
-      });
+      }
     }
-  });
+  }
   return result;
 }
 
@@ -98,10 +111,10 @@ function newResults(ruleList) {
     const results = [];
     const keys = Object.keys(lintResults);
     keys.sort();
-    keys.forEach(function forFile(file) {
+    for (const file of keys) {
       const fileResults = lintResults[file];
       if (Array.isArray(fileResults)) {
-        fileResults.forEach(function forResult(result) {
+        for (const result of fileResults) {
           const ruleMoniker = result.ruleNames ?
             result.ruleNames.join("/") :
             (result.ruleName + "/" + result.ruleAlias);
@@ -116,30 +129,32 @@ function newResults(ruleList) {
             (result.errorContext ?
               " [Context: \"" + result.errorContext + "\"]" :
               ""));
-        });
+        }
       } else {
         if (!ruleNameToRule) {
           ruleNameToRule = {};
-          ruleList.forEach(function forRule(rule) {
+          for (const rule of ruleList) {
             const ruleName = rule.names[0].toUpperCase();
             ruleNameToRule[ruleName] = rule;
-          });
+          }
         }
-        Object.keys(fileResults).forEach(function forRule(ruleName) {
+        for (const [ ruleName, ruleResults ] of Object.entries(fileResults)) {
           const rule = ruleNameToRule[ruleName.toUpperCase()];
-          const ruleResults = fileResults[ruleName];
-          ruleResults.forEach(function forLine(lineNumber) {
+          for (const lineNumber of ruleResults) {
+            // @ts-ignore
             const nameIndex = Math.min(useAlias ? 1 : 0, rule.names.length - 1);
             const result =
               file + ": " +
               lineNumber + ": " +
+              // @ts-ignore
               rule.names[nameIndex] + " " +
+              // @ts-ignore
               rule.description;
             results.push(result);
-          });
-        });
+          }
+        }
       }
-    });
+    }
     return results.join("\n");
   }
   Object.defineProperty(lintResults, "toString", { "value": toString });
@@ -175,34 +190,53 @@ function removeFrontMatter(content, frontMatter) {
 }
 
 /**
- * Annotate tokens with line/lineNumber.
+ * Freeze all freeze-able members of a token and its children.
+ *
+ * @param {MarkdownItToken} token A markdown-it token.
+ * @returns {void}
+ */
+function freezeToken(token) {
+  if (token.attrs) {
+    for (const attr of token.attrs) {
+      Object.freeze(attr);
+    }
+    Object.freeze(token.attrs);
+  }
+  if (token.children) {
+    for (const child of token.children) {
+      freezeToken(child);
+    }
+    Object.freeze(token.children);
+  }
+  if (token.map) {
+    Object.freeze(token.map);
+  }
+  Object.freeze(token);
+}
+
+/**
+ * Annotate tokens with line/lineNumber and freeze them.
  *
  * @param {MarkdownItToken[]} tokens Array of markdown-it tokens.
  * @param {string[]} lines Lines of Markdown content.
  * @returns {void}
  */
-function annotateTokens(tokens, lines) {
-  let tableMap = null;
-  tokens.forEach(function forToken(token) {
-    // Handle missing maps for table head/body
-    if (
-      (token.type === "thead_open") ||
-      (token.type === "tbody_open")
-    ) {
-      tableMap = [ ...token.map ];
-    } else if (
-      (token.type === "tr_close") &&
-      tableMap
-    ) {
-      tableMap[0]++;
-    } else if (
-      (token.type === "thead_close") ||
-      (token.type === "tbody_close")
-    ) {
-      tableMap = null;
+function annotateAndFreezeTokens(tokens, lines) {
+  let trMap = null;
+  for (const token of tokens) {
+    // Provide missing maps for table content
+    if (token.type === "tr_open") {
+      trMap = token.map;
+    } else if (token.type === "tr_close") {
+      trMap = null;
     }
-    if (tableMap && !token.map) {
-      token.map = [ ...tableMap ];
+    if (!token.map && trMap) {
+      token.map = [ ...trMap ];
+    }
+    // Adjust maps for math blocks
+    if (helpers.isMathBlock(token) && token.map[1]) {
+      // markdown-it-texmath plugin does not account for math_block_end
+      token.map[1]++;
     }
     // Update token metadata
     if (token.map) {
@@ -212,16 +246,17 @@ function annotateTokens(tokens, lines) {
       while (token.map[1] && !((lines[token.map[1] - 1] || "").trim())) {
         token.map[1]--;
       }
-      // Annotate children with lineNumber
-      let lineNumber = token.lineNumber;
+    }
+    // Annotate children with lineNumber
+    if (token.children) {
       const codeSpanExtraLines = [];
-      helpers.forEachInlineCodeSpan(
-        token.content,
-        function handleInlineCodeSpan(code) {
+      if (token.children.some((child) => child.type === "code_inline")) {
+        helpers.forEachInlineCodeSpan(token.content, (code) => {
           codeSpanExtraLines.push(code.split(helpers.newLineRe).length - 1);
-        }
-      );
-      (token.children || []).forEach(function forChild(child) {
+        });
+      }
+      let lineNumber = token.lineNumber;
+      for (const child of token.children) {
         child.lineNumber = lineNumber;
         child.line = lines[lineNumber - 1];
         if ((child.type === "softbreak") || (child.type === "hardbreak")) {
@@ -229,9 +264,11 @@ function annotateTokens(tokens, lines) {
         } else if (child.type === "code_inline") {
           lineNumber += codeSpanExtraLines.shift();
         }
-      });
+      }
     }
-  });
+    freezeToken(token);
+  }
+  Object.freeze(tokens);
 }
 
 /**
@@ -243,24 +280,24 @@ function annotateTokens(tokens, lines) {
 function mapAliasToRuleNames(ruleList) {
   const aliasToRuleNames = {};
   // const tagToRuleNames = {};
-  ruleList.forEach(function forRule(rule) {
+  for (const rule of ruleList) {
     const ruleName = rule.names[0].toUpperCase();
     // The following is useful for updating README.md:
     // console.log(
     //   "* **[" + ruleName + "](doc/Rules.md#" + ruleName.toLowerCase() +
     //    ")** *" + rule.names.slice(1).join("/") + "* - " + rule.description);
-    rule.names.forEach(function forName(name) {
+    for (const name of rule.names) {
       const nameUpper = name.toUpperCase();
       aliasToRuleNames[nameUpper] = [ ruleName ];
-    });
-    rule.tags.forEach(function forTag(tag) {
+    }
+    for (const tag of rule.tags) {
       const tagUpper = tag.toUpperCase();
       const ruleNames = aliasToRuleNames[tagUpper] || [];
       ruleNames.push(ruleName);
       aliasToRuleNames[tagUpper] = ruleNames;
       // tagToRuleNames[tag] = ruleName;
-    });
-  });
+    }
+  }
   // The following is useful for updating README.md:
   // Object.keys(tagToRuleNames).sort().forEach(function forTag(tag) {
   //   console.log("* **" + tag + "** - " +
@@ -285,14 +322,14 @@ function getEffectiveConfig(ruleList, config, aliasToRuleNames) {
   );
   const ruleDefault = (defaultKey.length === 0) || !!config[defaultKey[0]];
   const effectiveConfig = {};
-  ruleList.forEach((rule) => {
+  for (const rule of ruleList) {
     const ruleName = rule.names[0].toUpperCase();
     effectiveConfig[ruleName] = ruleDefault;
-  });
-  deprecatedRuleNames.forEach((ruleName) => {
+  }
+  for (const ruleName of deprecatedRuleNames) {
     effectiveConfig[ruleName] = false;
-  });
-  Object.keys(config).forEach((key) => {
+  }
+  for (const key of Object.keys(config)) {
     let value = config[key];
     if (value) {
       if (!(value instanceof Object)) {
@@ -302,13 +339,46 @@ function getEffectiveConfig(ruleList, config, aliasToRuleNames) {
       value = false;
     }
     const keyUpper = key.toUpperCase();
-    (aliasToRuleNames[keyUpper] || []).forEach((ruleName) => {
+    for (const ruleName of (aliasToRuleNames[keyUpper] || [])) {
       effectiveConfig[ruleName] = value;
-    });
-  });
+    }
+  }
   return effectiveConfig;
 }
 
+/**
+ * Parse the content of a configuration file.
+ *
+ * @param {string} name Name of the configuration file.
+ * @param {string} content Configuration content.
+ * @param {ConfigurationParser[] | null} [parsers] Parsing function(s).
+ * @returns {Object} Configuration object and error message.
+ */
+function parseConfiguration(name, content, parsers) {
+  let config = null;
+  let message = "";
+  const errors = [];
+  let index = 0;
+  // Try each parser
+  (parsers || [ JSON.parse ]).every((parser) => {
+    try {
+      config = parser(content);
+    } catch (error) {
+      errors.push(`Parser ${index++}: ${error.message}`);
+    }
+    return !config;
+  });
+  // Message if unable to parse
+  if (!config) {
+    errors.unshift(`Unable to parse '${name}'`);
+    message = errors.join("; ");
+  }
+  return {
+    config,
+    message
+  };
+}
+
 /**
  * Create a mapping of enabled rules per line.
  *
@@ -317,6 +387,7 @@ function getEffectiveConfig(ruleList, config, aliasToRuleNames) {
  * @param {string[]} frontMatterLines List of front matter lines.
  * @param {boolean} noInlineConfig Whether to allow inline configuration.
  * @param {Configuration} config Configuration object.
+ * @param {ConfigurationParser[] | null} configParsers Configuration parsers.
  * @param {Object.<string, string[]>} aliasToRuleNames Map of alias to rule
  * names.
  * @returns {Object} Effective configuration and enabled rules per line number.
@@ -327,6 +398,7 @@ function getEnabledRulesPerLineNumber(
   frontMatterLines,
   noInlineConfig,
   config,
+  configParsers,
   aliasToRuleNames) {
   // Shared variables
   let enabledRules = {};
@@ -335,92 +407,101 @@ function getEnabledRulesPerLineNumber(
   const enabledRulesPerLineNumber = new Array(1 + frontMatterLines.length);
   // Helper functions
   // eslint-disable-next-line jsdoc/require-jsdoc
-  function handleInlineConfig(perLine, forEachMatch, forEachLine) {
-    const input = perLine ? lines : [ lines.join("\n") ];
-    input.forEach((line, lineIndex) => {
+  function handleInlineConfig(input, forEachMatch, forEachLine) {
+    for (const [ lineIndex, line ] of input.entries()) {
       if (!noInlineConfig) {
         let match = null;
-        while ((match = helpers.inlineCommentRe.exec(line))) {
-          const action = (match[1] || match[3]).toUpperCase();
-          const parameter = match[2] || match[4];
+        while ((match = helpers.inlineCommentStartRe.exec(line))) {
+          const action = match[2].toUpperCase();
+          const startIndex = match.index + match[1].length;
+          const endIndex = line.indexOf("-->", startIndex);
+          if (endIndex === -1) {
+            break;
+          }
+          const parameter = line.slice(startIndex, endIndex);
           forEachMatch(action, parameter, lineIndex + 1);
         }
       }
       if (forEachLine) {
         forEachLine();
       }
-    });
+    }
   }
   // eslint-disable-next-line jsdoc/require-jsdoc
   function configureFile(action, parameter) {
     if (action === "CONFIGURE-FILE") {
-      try {
-        const json = JSON.parse(parameter);
+      const { "config": parsed } = parseConfiguration(
+        "CONFIGURE-FILE", parameter, configParsers
+      );
+      if (parsed) {
         config = {
           ...config,
-          ...json
+          ...parsed
         };
-      } catch {
-        // Ignore parse errors for inline configuration
       }
     }
   }
   // eslint-disable-next-line jsdoc/require-jsdoc
   function applyEnableDisable(action, parameter, state) {
+    state = { ...state };
     const enabled = (action.startsWith("ENABLE"));
-    const items = parameter ?
-      parameter.trim().toUpperCase().split(/\s+/) :
-      allRuleNames;
-    items.forEach((nameUpper) => {
-      (aliasToRuleNames[nameUpper] || []).forEach((ruleName) => {
+    const trimmed = parameter && parameter.trim();
+    const items = trimmed ? trimmed.toUpperCase().split(/\s+/) : allRuleNames;
+    for (const nameUpper of items) {
+      for (const ruleName of (aliasToRuleNames[nameUpper] || [])) {
         state[ruleName] = enabled;
-      });
-    });
+      }
+    }
+    return state;
   }
   // eslint-disable-next-line jsdoc/require-jsdoc
   function enableDisableFile(action, parameter) {
     if ((action === "ENABLE-FILE") || (action === "DISABLE-FILE")) {
-      applyEnableDisable(action, parameter, enabledRules);
+      enabledRules = applyEnableDisable(action, parameter, enabledRules);
     }
   }
   // eslint-disable-next-line jsdoc/require-jsdoc
   function captureRestoreEnableDisable(action, parameter) {
     if (action === "CAPTURE") {
-      capturedRules = { ...enabledRules };
+      capturedRules = enabledRules;
     } else if (action === "RESTORE") {
-      enabledRules = { ...capturedRules };
+      enabledRules = capturedRules;
     } else if ((action === "ENABLE") || (action === "DISABLE")) {
-      enabledRules = { ...enabledRules };
-      applyEnableDisable(action, parameter, enabledRules);
+      enabledRules = applyEnableDisable(action, parameter, enabledRules);
     }
   }
   // eslint-disable-next-line jsdoc/require-jsdoc
   function updateLineState() {
-    enabledRulesPerLineNumber.push({ ...enabledRules });
+    enabledRulesPerLineNumber.push(enabledRules);
   }
   // eslint-disable-next-line jsdoc/require-jsdoc
-  function disableNextLine(action, parameter, lineNumber) {
-    if (action === "DISABLE-NEXT-LINE") {
-      applyEnableDisable(
-        action,
-        parameter,
-        enabledRulesPerLineNumber[lineNumber + 1] || {}
-      );
+  function disableLineNextLine(action, parameter, lineNumber) {
+    const disableLine = (action === "DISABLE-LINE");
+    const disableNextLine = (action === "DISABLE-NEXT-LINE");
+    if (disableLine || disableNextLine) {
+      const nextLineNumber =
+        frontMatterLines.length + lineNumber + (disableNextLine ? 1 : 0);
+      enabledRulesPerLineNumber[nextLineNumber] =
+        applyEnableDisable(
+          action,
+          parameter,
+          enabledRulesPerLineNumber[nextLineNumber] || {}
+        );
     }
   }
   // Handle inline comments
-  handleInlineConfig(false, configureFile);
+  handleInlineConfig([ lines.join("\n") ], configureFile);
   const effectiveConfig = getEffectiveConfig(
     ruleList, config, aliasToRuleNames);
-  ruleList.forEach((rule) => {
+  for (const rule of ruleList) {
     const ruleName = rule.names[0].toUpperCase();
     allRuleNames.push(ruleName);
     enabledRules[ruleName] = !!effectiveConfig[ruleName];
-  });
+  }
   capturedRules = enabledRules;
-  handleInlineConfig(true, enableDisableFile);
-  handleInlineConfig(true, captureRestoreEnableDisable, updateLineState);
-  handleInlineConfig(true, disableNextLine);
+  handleInlineConfig(lines, enableDisableFile);
+  handleInlineConfig(lines, captureRestoreEnableDisable, updateLineState);
+  handleInlineConfig(lines, disableLineNextLine);
   // Return results
   return {
     effectiveConfig,
@@ -428,38 +509,6 @@ function getEnabledRulesPerLineNumber(
   };
 }
 
-/**
- * Compare function for Array.prototype.sort for ascending order of errors.
- *
- * @param {LintError} a First error.
- * @param {LintError} b Second error.
- * @returns {number} Positive value if a>b, negative value if b<a, 0 otherwise.
- */
-function lineNumberComparison(a, b) {
-  return a.lineNumber - b.lineNumber;
-}
-
-/**
- * Filter function to include everything.
- *
- * @returns {boolean} True.
- */
-function filterAllValues() {
-  return true;
-}
-
-/**
- * Function to return unique values from a sorted errors array.
- *
- * @param {LintError} value Error instance.
- * @param {number} index Index in array.
- * @param {LintError[]} array Array of errors.
- * @returns {boolean} Filter value.
- */
-function uniqueFilterForSortedErrors(value, index, array) {
-  return (index === 0) || (value.lineNumber > array[index - 1].lineNumber);
-}
-
 /**
  * Lints a string containing Markdown content.
  *
@@ -468,6 +517,7 @@ function uniqueFilterForSortedErrors(value, index, array) {
  * @param {string} content Markdown content.
  * @param {Object} md Instance of markdown-it.
  * @param {Configuration} config Configuration object.
+ * @param {ConfigurationParser[] | null} configParsers Configuration parsers.
  * @param {RegExp} frontMatter Regular expression for front matter.
  * @param {boolean} handleRuleFailures Whether to handle exceptions in rules.
  * @param {boolean} noInlineConfig Whether to allow inline configuration.
@@ -481,6 +531,7 @@ function lintContent(
   content,
   md,
   config,
+  configParsers,
   frontMatter,
   handleRuleFailures,
   noInlineConfig,
@@ -490,47 +541,64 @@ function lintContent(
   content = content.replace(/^\uFEFF/, "");
   // Remove front matter
   const removeFrontMatterResult = removeFrontMatter(content, frontMatter);
-  const frontMatterLines = removeFrontMatterResult.frontMatterLines;
-  // Ignore the content of HTML comments
-  content = helpers.clearHtmlCommentText(removeFrontMatterResult.content);
-  // Parse content into tokens and lines
-  const tokens = md.parse(content, {});
-  const lines = content.split(helpers.newLineRe);
-  annotateTokens(tokens, lines);
-  const aliasToRuleNames = mapAliasToRuleNames(ruleList);
+  const { frontMatterLines } = removeFrontMatterResult;
+  content = removeFrontMatterResult.content;
+  // Get enabled rules per line (with HTML comments present)
   const { effectiveConfig, enabledRulesPerLineNumber } =
     getEnabledRulesPerLineNumber(
       ruleList,
-      lines,
+      content.split(helpers.newLineRe),
       frontMatterLines,
       noInlineConfig,
       config,
-      aliasToRuleNames
+      configParsers,
+      mapAliasToRuleNames(ruleList)
     );
-  // Create parameters for rules
-  const params = {
+  // Hide the content of HTML comments from rules, etc.
+  content = helpers.clearHtmlCommentText(content);
+  // Parse content into tokens and lines
+  const tokens = md.parse(content, {});
+  const lines = content.split(helpers.newLineRe);
+  annotateAndFreezeTokens(tokens, lines);
+  // Create (frozen) parameters for rules
+  const paramsBase = {
     name,
     tokens,
-    lines,
-    frontMatterLines
+    "lines": Object.freeze(lines),
+    "frontMatterLines": Object.freeze(frontMatterLines)
   };
-  cache.lineMetadata(helpers.getLineMetadata(params));
-  cache.flattenedLists(helpers.flattenLists(params.tokens));
-  cache.inlineCodeSpanRanges(helpers.inlineCodeSpanRanges(params.lines));
+  const lineMetadata =
+    helpers.getLineMetadata(paramsBase);
+  const codeBlockAndSpanRanges =
+    helpers.codeBlockAndSpanRanges(paramsBase, lineMetadata);
+  const flattenedLists =
+    helpers.flattenLists(paramsBase.tokens);
+  const htmlElementRanges =
+    helpers.htmlElementRanges(paramsBase, lineMetadata);
+  const referenceLinkImageData =
+    helpers.getReferenceLinkImageData(lineMetadata);
+  cache.set({
+    codeBlockAndSpanRanges,
+    flattenedLists,
+    htmlElementRanges,
+    lineMetadata,
+    referenceLinkImageData
+  });
   // Function to run for each rule
-  const result = (resultVersion === 0) ? {} : [];
+  let results = [];
   // eslint-disable-next-line jsdoc/require-jsdoc
   function forRule(rule) {
     // Configure rule
-    const ruleNameFriendly = rule.names[0];
-    const ruleName = ruleNameFriendly.toUpperCase();
-    params.config = effectiveConfig[ruleName];
+    const ruleName = rule.names[0].toUpperCase();
+    const params = {
+      ...paramsBase,
+      "config": effectiveConfig[ruleName]
+    };
     // eslint-disable-next-line jsdoc/require-jsdoc
     function throwError(property) {
       throw new Error(
         "Property '" + property + "' of onError parameter is incorrect.");
     }
-    const errors = [];
     // eslint-disable-next-line jsdoc/require-jsdoc
     function onError(errorInfo) {
       if (!errorInfo ||
@@ -539,6 +607,10 @@ function lintContent(
         (errorInfo.lineNumber > lines.length)) {
         throwError("lineNumber");
       }
+      const lineNumber = errorInfo.lineNumber + frontMatterLines.length;
+      if (!enabledRulesPerLineNumber[lineNumber][ruleName]) {
+        return;
+      }
       if (errorInfo.detail &&
         !helpers.isString(errorInfo.detail)) {
         throwError("detail");
@@ -549,12 +621,12 @@ function lintContent(
       }
       if (errorInfo.range &&
         (!Array.isArray(errorInfo.range) ||
-         (errorInfo.range.length !== 2) ||
-         !helpers.isNumber(errorInfo.range[0]) ||
-         (errorInfo.range[0] < 1) ||
-         !helpers.isNumber(errorInfo.range[1]) ||
-         (errorInfo.range[1] < 1) ||
-         ((errorInfo.range[0] + errorInfo.range[1] - 1) >
+          (errorInfo.range.length !== 2) ||
+          !helpers.isNumber(errorInfo.range[0]) ||
+          (errorInfo.range[0] < 1) ||
+          !helpers.isNumber(errorInfo.range[1]) ||
+          (errorInfo.range[1] < 1) ||
+          ((errorInfo.range[0] + errorInfo.range[1] - 1) >
           lines[errorInfo.lineNumber - 1].length))) {
         throwError("range");
       }
@@ -599,78 +671,114 @@ function lintContent(
           cleanFixInfo.insertText = fixInfo.insertText;
         }
       }
-      errors.push({
-        "lineNumber": errorInfo.lineNumber + frontMatterLines.length,
-        "detail": errorInfo.detail || null,
-        "context": errorInfo.context || null,
-        "range": errorInfo.range ? [ ...errorInfo.range ] : null,
+      results.push({
+        lineNumber,
+        "ruleName": rule.names[0],
+        "ruleNames": rule.names,
+        "ruleDescription": rule.description,
+        "ruleInformation": rule.information ? rule.information.href : null,
+        "errorDetail": errorInfo.detail || null,
+        "errorContext": errorInfo.context || null,
+        "errorRange": errorInfo.range ? [ ...errorInfo.range ] : null,
         "fixInfo": fixInfo ? cleanFixInfo : null
       });
     }
-    // Call (possibly external) rule function
-    if (handleRuleFailures) {
-      try {
-        rule.function(params, onError);
-      } catch (error) {
-        onError({
-          "lineNumber": 1,
-          "detail": `This rule threw an exception: ${error.message}`
-        });
+    // Call (possibly external) rule function to report errors
+    const catchCallsOnError = (error) => onError({
+      "lineNumber": 1,
+      "detail": `This rule threw an exception: ${error.message || error}`
+    });
+    const invokeRuleFunction = () => rule.function(params, onError);
+    if (rule.asynchronous) {
+      // Asynchronous rule, ensure it returns a Promise
+      const ruleFunctionPromise =
+        Promise.resolve().then(invokeRuleFunction);
+      return handleRuleFailures ?
+        ruleFunctionPromise.catch(catchCallsOnError) :
+        ruleFunctionPromise;
+    }
+    // Synchronous rule
+    try {
+      invokeRuleFunction();
+    } catch (error) {
+      if (handleRuleFailures) {
+        catchCallsOnError(error);
+      } else {
+        throw error;
       }
-    } else {
-      rule.function(params, onError);
     }
-    // Record any errors (significant performance benefit from length check)
-    if (errors.length > 0) {
-      errors.sort(lineNumberComparison);
-      const filteredErrors = errors
-        .filter((resultVersion === 3) ?
-          filterAllValues :
-          uniqueFilterForSortedErrors)
-        .filter(function removeDisabledRules(error) {
-          return enabledRulesPerLineNumber[error.lineNumber][ruleName];
-        })
-        .map(function formatResults(error) {
-          if (resultVersion === 0) {
-            return error.lineNumber;
-          }
-          const errorObject = {};
-          errorObject.lineNumber = error.lineNumber;
-          if (resultVersion === 1) {
-            errorObject.ruleName = ruleNameFriendly;
-            errorObject.ruleAlias = rule.names[1] || rule.names[0];
-          } else {
-            errorObject.ruleNames = rule.names;
-          }
-          errorObject.ruleDescription = rule.description;
-          errorObject.ruleInformation =
-            rule.information ? rule.information.href : null;
-          errorObject.errorDetail = error.detail;
-          errorObject.errorContext = error.context;
-          errorObject.errorRange = error.range;
-          if (resultVersion === 3) {
-            errorObject.fixInfo = error.fixInfo;
-          }
-          return errorObject;
-        });
-      if (filteredErrors.length > 0) {
-        if (resultVersion === 0) {
-          result[ruleNameFriendly] = filteredErrors;
-        } else {
-          Array.prototype.push.apply(result, filteredErrors);
-        }
+    return null;
+  }
+  // eslint-disable-next-line jsdoc/require-jsdoc
+  function formatResults() {
+    // Sort results by rule name by line number
+    results.sort((a, b) => (
+      a.ruleName.localeCompare(b.ruleName) ||
+      a.lineNumber - b.lineNumber
+    ));
+    if (resultVersion < 3) {
+      // Remove fixInfo and multiple errors for the same rule and line number
+      const noPrevious = {
+        "ruleName": null,
+        "lineNumber": -1
+      };
+      results = results.filter((error, index, array) => {
+        delete error.fixInfo;
+        const previous = array[index - 1] || noPrevious;
+        return (
+          (error.ruleName !== previous.ruleName) ||
+          (error.lineNumber !== previous.lineNumber)
+        );
+      });
+    }
+    if (resultVersion === 0) {
+      // Return a dictionary of rule->[line numbers]
+      const dictionary = {};
+      for (const error of results) {
+        const ruleLines = dictionary[error.ruleName] || [];
+        ruleLines.push(error.lineNumber);
+        dictionary[error.ruleName] = ruleLines;
+      }
+      // @ts-ignore
+      results = dictionary;
+    } else if (resultVersion === 1) {
+      // Use ruleAlias instead of ruleNames
+      for (const error of results) {
+        error.ruleAlias = error.ruleNames[1] || error.ruleName;
+        delete error.ruleNames;
+      }
+    } else {
+      // resultVersion 2 or 3: Remove unwanted ruleName
+      for (const error of results) {
+        delete error.ruleName;
       }
     }
+    return results;
   }
   // Run all rules
+  const ruleListAsync = ruleList.filter((rule) => rule.asynchronous);
+  const ruleListSync = ruleList.filter((rule) => !rule.asynchronous);
+  const ruleListAsyncFirst = [
+    ...ruleListAsync,
+    ...ruleListSync
+  ];
+  const callbackSuccess = () => callback(null, formatResults());
+  const callbackError =
+    (error) => callback(error instanceof Error ? error : new Error(error));
   try {
-    ruleList.forEach(forRule);
+    const ruleResults = ruleListAsyncFirst.map(forRule);
+    if (ruleListAsync.length > 0) {
+      Promise.all(ruleResults.slice(0, ruleListAsync.length))
+        .then(callbackSuccess)
+        .catch(callbackError);
+    } else {
+      callbackSuccess();
+    }
   } catch (error) {
+    callbackError(error);
+  } finally {
     cache.clear();
-    return callback(error);
   }
-  cache.clear();
-  return callback(null, result);
 }
 
 /**
@@ -680,6 +788,7 @@ function lintContent(
  * @param {string} file Path of file to lint.
  * @param {Object} md Instance of markdown-it.
  * @param {Configuration} config Configuration object.
+ * @param {ConfigurationParser[] | null} configParsers Configuration parsers.
  * @param {RegExp} frontMatter Regular expression for front matter.
  * @param {boolean} handleRuleFailures Whether to handle exceptions in rules.
  * @param {boolean} noInlineConfig Whether to allow inline configuration.
@@ -694,6 +803,7 @@ function lintFile(
   file,
   md,
   config,
+  configParsers,
   frontMatter,
   handleRuleFailures,
   noInlineConfig,
@@ -706,8 +816,19 @@ function lintFile(
     if (err) {
       return callback(err);
     }
-    return lintContent(ruleList, file, content, md, config, frontMatter,
-      handleRuleFailures, noInlineConfig, resultVersion, callback);
+    return lintContent(
+      ruleList,
+      file,
+      content,
+      md,
+      config,
+      configParsers,
+      frontMatter,
+      handleRuleFailures,
+      noInlineConfig,
+      resultVersion,
+      callback
+    );
   }
   // Make a/synchronous call to read file
   if (synchronous) {
@@ -731,9 +852,10 @@ function lintInput(options, synchronous, callback) {
   callback = callback || function noop() {};
   // eslint-disable-next-line unicorn/prefer-spread
   const ruleList = rules.concat(options.customRules || []);
-  const ruleErr = validateRuleList(ruleList);
+  const ruleErr = validateRuleList(ruleList, synchronous);
   if (ruleErr) {
-    return callback(ruleErr);
+    callback(ruleErr);
+    return;
   }
   let files = [];
   if (Array.isArray(options.files)) {
@@ -744,114 +866,99 @@ function lintInput(options, synchronous, callback) {
   const strings = options.strings || {};
   const stringsKeys = Object.keys(strings);
   const config = options.config || { "default": true };
+  const configParsers = options.configParsers || null;
   const frontMatter = (options.frontMatter === undefined) ?
     helpers.frontMatterRe : options.frontMatter;
   const handleRuleFailures = !!options.handleRuleFailures;
   const noInlineConfig = !!options.noInlineConfig;
   const resultVersion = (options.resultVersion === undefined) ?
-    2 : options.resultVersion;
+    3 : options.resultVersion;
   const md = markdownIt({ "html": true });
   const markdownItPlugins = options.markdownItPlugins || [];
-  markdownItPlugins.forEach(function forPlugin(plugin) {
+  for (const plugin of markdownItPlugins) {
     // @ts-ignore
     md.use(...plugin);
-  });
+  }
   const fs = options.fs || require("fs");
   const results = newResults(ruleList);
   let done = false;
-  // Linting of strings is always synchronous
-  let syncItem = null;
+  let concurrency = 0;
   // eslint-disable-next-line jsdoc/require-jsdoc
-  function syncCallback(err, result) {
-    if (err) {
-      done = true;
-      return callback(err);
+  function lintWorker() {
+    let currentItem = null;
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    function lintWorkerCallback(err, result) {
+      concurrency--;
+      if (err) {
+        done = true;
+        return callback(err);
+      }
+      results[currentItem] = result;
+      if (!synchronous) {
+        lintWorker();
+      }
+      return null;
     }
-    results[syncItem] = result;
-    return null;
-  }
-  while (!done && (syncItem = stringsKeys.shift())) {
-    lintContent(
-      ruleList,
-      syncItem,
-      strings[syncItem] || "",
-      md,
-      config,
-      frontMatter,
-      handleRuleFailures,
-      noInlineConfig,
-      resultVersion,
-      syncCallback
-    );
-  }
-  if (synchronous) {
-    // Lint files synchronously
-    while (!done && (syncItem = files.shift())) {
+    if (done) {
+      // Abort for error or nothing left to do
+    } else if (files.length > 0) {
+      // Lint next file
+      concurrency++;
+      currentItem = files.shift();
       lintFile(
         ruleList,
-        syncItem,
+        currentItem,
         md,
         config,
+        configParsers,
         frontMatter,
         handleRuleFailures,
         noInlineConfig,
         resultVersion,
         fs,
         synchronous,
-        syncCallback
+        lintWorkerCallback
       );
-    }
-    return done || callback(null, results);
-  }
-  // Lint files asynchronously
-  let concurrency = 0;
-  // eslint-disable-next-line jsdoc/require-jsdoc
-  function lintConcurrently() {
-    const asyncItem = files.shift();
-    if (done) {
-      // Nothing to do
-    } else if (asyncItem) {
+    } else if ((currentItem = stringsKeys.shift())) {
+      // Lint next string
       concurrency++;
-      lintFile(
+      lintContent(
         ruleList,
-        asyncItem,
+        currentItem,
+        strings[currentItem] || "",
         md,
         config,
+        configParsers,
         frontMatter,
         handleRuleFailures,
         noInlineConfig,
         resultVersion,
-        fs,
-        synchronous,
-        (err, result) => {
-          concurrency--;
-          if (err) {
-            done = true;
-            return callback(err);
-          }
-          results[asyncItem] = result;
-          lintConcurrently();
-          return null;
-        }
+        lintWorkerCallback
       );
     } else if (concurrency === 0) {
+      // Finish
       done = true;
       return callback(null, results);
     }
     return null;
   }
-  // Testing on a Raspberry Pi 4 Model B with an artificial 5ms file access
-  // delay suggests that a concurrency factor of 8 can eliminate the impact
-  // of that delay (i.e., total time is the same as with no delay).
-  lintConcurrently();
-  lintConcurrently();
-  lintConcurrently();
-  lintConcurrently();
-  lintConcurrently();
-  lintConcurrently();
-  lintConcurrently();
-  lintConcurrently();
-  return null;
+  if (synchronous) {
+    while (!done) {
+      lintWorker();
+    }
+  } else {
+    // Testing on a Raspberry Pi 4 Model B with an artificial 5ms file access
+    // delay suggests that a concurrency factor of 8 can eliminate the impact
+    // of that delay (i.e., total time is the same as with no delay).
+    lintWorker();
+    lintWorker();
+    lintWorker();
+    lintWorker();
+    lintWorker();
+    lintWorker();
+    lintWorker();
+    lintWorker();
+  }
 }
 
 /**
@@ -874,6 +981,7 @@ const markdownlintPromisify = promisify && promisify(markdownlint);
  * @returns {Promise<LintResults>} Results object.
  */
 function markdownlintPromise(options) {
+  // @ts-ignore
   return markdownlintPromisify(options);
 }
 
@@ -884,48 +992,17 @@ function markdownlintPromise(options) {
  * @returns {LintResults} Results object.
  */
 function markdownlintSync(options) {
-  let results = null;
+  let results = {};
   lintInput(options, true, function callback(error, res) {
     if (error) {
       throw error;
     }
     results = res;
   });
+  // @ts-ignore
   return results;
 }
 
-/**
- * Parse the content of a configuration file.
- *
- * @param {string} name Name of the configuration file.
- * @param {string} content Configuration content.
- * @param {ConfigurationParser[]} parsers Parsing function(s).
- * @returns {Object} Configuration object and error message.
- */
-function parseConfiguration(name, content, parsers) {
-  let config = null;
-  let message = "";
-  const errors = [];
-  // Try each parser
-  (parsers || [ JSON.parse ]).every((parser) => {
-    try {
-      config = parser(content);
-    } catch (error) {
-      errors.push(error.message);
-    }
-    return !config;
-  });
-  // Message if unable to parse
-  if (!config) {
-    errors.unshift(`Unable to parse '${name}'`);
-    message = errors.join("; ");
-  }
-  return {
-    config,
-    message
-  };
-}
-
 /**
  * Resolve referenced "extends" path in a configuration file
  * using path.resolve() with require.resolve() as a fallback.
@@ -933,7 +1010,7 @@ function parseConfiguration(name, content, parsers) {
  * @param {string} configFile Configuration file name.
  * @param {string} referenceId Referenced identifier to resolve.
  * @param {Object} fs File system implementation.
- * @param {ResolveConfigExtendsCallback} [callback] Callback (err, result)
+ * @param {ResolveConfigExtendsCallback} callback Callback (err, result)
  * function.
  * @returns {void}
  */
@@ -1003,6 +1080,7 @@ function readConfig(file, parsers, fs, callback) {
     } else {
       // @ts-ignore
       callback = parsers;
+      // @ts-ignore
       parsers = null;
     }
   }
@@ -1010,14 +1088,18 @@ function readConfig(file, parsers, fs, callback) {
     fs = require("fs");
   }
   // Read file
+  const os = require("os");
+  file = helpers.expandTildePath(file, os);
   fs.readFile(file, "utf8", (err, content) => {
     if (err) {
+      // @ts-ignore
       return callback(err);
     }
     // Try to parse file
     // @ts-ignore
     const { config, message } = parseConfiguration(file, content, parsers);
     if (!config) {
+      // @ts-ignore
       return callback(new Error(message));
     }
     // Extend configuration
@@ -1026,16 +1108,19 @@ function readConfig(file, parsers, fs, callback) {
       delete config.extends;
       return resolveConfigExtends(
         file,
-        configExtends,
+        helpers.expandTildePath(configExtends, os),
         fs,
         (_, resolvedExtends) => readConfig(
+          // @ts-ignore
           resolvedExtends,
           parsers,
           fs,
           (errr, extendsConfig) => {
             if (errr) {
+              // @ts-ignore
               return callback(errr);
             }
+            // @ts-ignore
             return callback(null, {
               ...extendsConfig,
               ...config
@@ -1044,6 +1129,7 @@ function readConfig(file, parsers, fs, callback) {
         )
       );
     }
+    // @ts-ignore
     return callback(null, config);
   });
 }
@@ -1077,6 +1163,8 @@ function readConfigSync(file, parsers, fs) {
     fs = require("fs");
   }
   // Read file
+  const os = require("os");
+  file = helpers.expandTildePath(file, os);
   const content = fs.readFileSync(file, "utf8");
   // Try to parse file
   const { config, message } = parseConfiguration(file, content, parsers);
@@ -1087,7 +1175,11 @@ function readConfigSync(file, parsers, fs) {
   const configExtends = config.extends;
   if (configExtends) {
     delete config.extends;
-    const resolvedExtends = resolveConfigExtendsSync(file, configExtends, fs);
+    const resolvedExtends = resolveConfigExtendsSync(
+      file,
+      helpers.expandTildePath(configExtends, os),
+      fs
+    );
     return {
       ...readConfigSync(resolvedExtends, parsers, fs),
       ...config
@@ -1102,7 +1194,7 @@ function readConfigSync(file, parsers, fs) {
  * @returns {string} SemVer string.
  */
 function getVersion() {
-  return require("../package.json").version;
+  return require("./constants").version;
 }
 
 // Export a/synchronous/Promise APIs
@@ -1172,7 +1264,7 @@ module.exports = markdownlint;
  *
  * @typedef {Object} RuleOnErrorInfo
  * @property {number} lineNumber Line number (1-based).
- * @property {string} [details] Details about the error.
+ * @property {string} [detail] Detail about the error.
  * @property {string} [context] Context for the error.
  * @property {number[]} [range] Column number (1-based) and length.
  * @property {RuleOnErrorFixInfo} [fixInfo] Fix information.
@@ -1196,6 +1288,7 @@ module.exports = markdownlint;
  * @property {string} description Rule description.
  * @property {URL} [information] Link to more information.
  * @property {string[]} tags Rule tag(s).
+ * @property {boolean} [asynchronous] True if asynchronous.
  * @property {RuleFunction} function Rule implementation.
  */
 
@@ -1203,16 +1296,17 @@ module.exports = markdownlint;
  * Configuration options.
  *
  * @typedef {Object} Options
- * @property {string[] | string} [files] Files to lint.
- * @property {Object.<string, string>} [strings] Strings to lint.
  * @property {Configuration} [config] Configuration object.
+ * @property {ConfigurationParser[]} [configParsers] Configuration parsers.
  * @property {Rule[] | Rule} [customRules] Custom rules.
+ * @property {string[] | string} [files] Files to lint.
  * @property {RegExp} [frontMatter] Front matter pattern.
+ * @property {Object} [fs] File system implementation.
  * @property {boolean} [handleRuleFailures] True to catch exceptions.
+ * @property {Plugin[]} [markdownItPlugins] Additional plugins.
  * @property {boolean} [noInlineConfig] True to ignore HTML directives.
  * @property {number} [resultVersion] Results object version.
- * @property {Plugin[]} [markdownItPlugins] Additional plugins.
- * @property {Object} [fs] File system implementation.
+ * @property {Object.<string, string>} [strings] Strings to lint.
  */
 
 /**