markdownlint 0.24.0 → 0.25.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,15 +15,14 @@ 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.
+ * @param {boolean} synchronous Whether to execute synchronously.
  * @returns {string} 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
@@ -62,6 +62,19 @@ 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) {
         const nameUpper = name.toUpperCase();
@@ -182,27 +195,21 @@ function removeFrontMatter(content, frontMatter) {
  * @returns {void}
  */
 function annotateTokens(tokens, lines) {
-  let tableMap = null;
+  let trMap = 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;
+    // Provide missing maps for table content
+    if (token.type === "tr_open") {
+      trMap = token.map;
+    } else if (token.type === "tr_close") {
+      trMap = null;
+    }
+    if (!token.map && trMap) {
+      token.map = [ ...trMap ];
     }
-    if (tableMap && !token.map) {
-      token.map = [ ...tableMap ];
+    // 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) {
@@ -335,8 +342,7 @@ 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") ];
+  function handleInlineConfig(input, forEachMatch, forEachLine) {
     input.forEach((line, lineIndex) => {
       if (!noInlineConfig) {
         let match = null;
@@ -367,6 +373,7 @@ function getEnabledRulesPerLineNumber(
   }
   // 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+/) :
@@ -376,40 +383,42 @@ function getEnabledRulesPerLineNumber(
         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] || {}
-      );
+      const nextLineNumber = frontMatterLines.length + lineNumber + 1;
+      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) => {
@@ -418,9 +427,9 @@ function getEnabledRulesPerLineNumber(
     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, disableNextLine);
   // Return results
   return {
     effectiveConfig,
@@ -428,38 +437,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.
  *
@@ -509,28 +486,28 @@ function lintContent(
     );
   // Create parameters for rules
   const params = {
-    name,
-    tokens,
-    lines,
-    frontMatterLines
+    "name": helpers.deepFreeze(name),
+    "tokens": helpers.deepFreeze(tokens),
+    "lines": helpers.deepFreeze(lines),
+    "frontMatterLines": helpers.deepFreeze(frontMatterLines)
   };
   cache.lineMetadata(helpers.getLineMetadata(params));
   cache.flattenedLists(helpers.flattenLists(params.tokens));
-  cache.inlineCodeSpanRanges(helpers.inlineCodeSpanRanges(params.lines));
+  cache.codeBlockAndSpanRanges(
+    helpers.codeBlockAndSpanRanges(params, cache.lineMetadata())
+  );
   // 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();
+    const ruleName = rule.names[0].toUpperCase();
     params.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 +516,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 +530,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 +580,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);
 }
 
 /**
@@ -731,7 +748,7 @@ 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);
   }
@@ -759,37 +776,32 @@ function lintInput(options, synchronous, callback) {
   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,
         frontMatter,
@@ -798,59 +810,48 @@ function lintInput(options, synchronous, callback) {
         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 (stringsKeys.length > 0) {
+      // Lint next string
       concurrency++;
-      lintFile(
+      currentItem = stringsKeys.shift();
+      lintContent(
         ruleList,
-        asyncItem,
+        currentItem,
+        strings[currentItem] || "",
         md,
         config,
         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();
+  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();
+  }
   return null;
 }
 
@@ -906,12 +907,13 @@ 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(error.message);
+      errors.push(`Parser ${index++}: ${error.message}`);
     }
     return !config;
   });
@@ -1102,7 +1104,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 +1174,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 +1198,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.
  */
 

package/lib/md007.js

@@ -13,12 +13,14 @@ module.exports = {
   "function": function MD007(params, onError) {
     const indent = Number(params.config.indent || 2);
     const startIndented = !!params.config.start_indented;
+    const startIndent = Number(params.config.start_indent || indent);
     flattenedLists().forEach((list) => {
       if (list.unordered && list.parentsUnordered) {
         list.items.forEach((item) => {
           const { lineNumber, line } = item;
-          const expectedNesting = list.nesting + (startIndented ? 1 : 0);
-          const expectedIndent = expectedNesting * indent;
+          const expectedIndent =
+            (startIndented ? startIndent : 0) +
+            (list.nesting * indent);
           const actualIndent = indentFor(item);
           let range = null;
           let editColumn = 1;