markdownlint 0.23.0 → 0.25.1

package/lib/markdownlint.js

@@ -2,23 +2,27 @@
 
 "use strict";
 
-const fs = require("fs");
 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");
 
-const deprecatedRuleNames = [ "MD002", "MD006" ];
+// @ts-ignore
+// eslint-disable-next-line camelcase, max-len, no-inline-comments, no-undef
+const dynamicRequire = (typeof __non_webpack_require__ === "undefined") ? require : /* c8 ignore next */ __non_webpack_require__;
+// Capture native require implementation for dynamic loading of modules
 
 /**
  * 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
@@ -58,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();
@@ -178,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.slice();
-    } 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.slice();
+    // 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) {
@@ -331,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;
@@ -363,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+/) :
@@ -372,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) => {
@@ -414,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,
@@ -424,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.
  *
@@ -505,27 +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));
+  cache.flattenedLists(helpers.flattenLists(params.tokens));
+  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 ||
@@ -534,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");
@@ -544,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");
       }
@@ -594,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);
 }
 
 /**
@@ -679,6 +701,7 @@ function lintContent(
  * @param {boolean} handleRuleFailures Whether to handle exceptions in rules.
  * @param {boolean} noInlineConfig Whether to allow inline configuration.
  * @param {number} resultVersion Version of the LintResults object to return.
+ * @param {Object} fs File system implementation.
  * @param {boolean} synchronous Whether to execute synchronously.
  * @param {Function} callback Callback (err, result) function.
  * @returns {void}
@@ -692,6 +715,7 @@ function lintFile(
   handleRuleFailures,
   noInlineConfig,
   resultVersion,
+  fs,
   synchronous,
   callback) {
   // eslint-disable-next-line jsdoc/require-jsdoc
@@ -704,10 +728,9 @@ function lintFile(
   }
   // Make a/synchronous call to read file
   if (synchronous) {
-    // @ts-ignore
-    lintContentWrapper(null, fs.readFileSync(file, helpers.utf8Encoding));
+    lintContentWrapper(null, fs.readFileSync(file, "utf8"));
   } else {
-    fs.readFile(file, helpers.utf8Encoding, lintContentWrapper);
+    fs.readFile(file, "utf8", lintContentWrapper);
   }
 }
 
@@ -725,13 +748,13 @@ 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);
   }
   let files = [];
   if (Array.isArray(options.files)) {
-    files = options.files.slice();
+    files = [ ...options.files ];
   } else if (options.files) {
     files = [ String(options.files) ];
   }
@@ -750,98 +773,85 @@ function lintInput(options, synchronous, callback) {
     // @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,
         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 (stringsKeys.length > 0) {
+      // Lint next string
       concurrency++;
-      lintFile(
+      currentItem = stringsKeys.shift();
+      lintContent(
         ruleList,
-        asyncItem,
+        currentItem,
+        strings[currentItem] || "",
         md,
         config,
         frontMatter,
         handleRuleFailures,
         noInlineConfig,
         resultVersion,
-        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;
 }
 
@@ -897,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;
   });
@@ -923,22 +934,55 @@ 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)
+ * function.
+ * @returns {void}
+ */
+function resolveConfigExtends(configFile, referenceId, fs, callback) {
+  const configFileDirname = path.dirname(configFile);
+  const resolvedExtendsFile = path.resolve(configFileDirname, referenceId);
+  fs.access(resolvedExtendsFile, (err) => {
+    if (err) {
+      // Not a file, try require.resolve
+      try {
+        return callback(null, dynamicRequire.resolve(
+          referenceId,
+          { "paths": [ configFileDirname ] }
+        ));
+      } catch {
+        // Unable to resolve, use resolvedExtendsFile
+      }
+    }
+    return callback(null, resolvedExtendsFile);
+  });
+}
+
+/**
+ * Resolve referenced "extends" path in a configuration file
+ * using path.resolve() with require.resolve() as a fallback.
+ *
+ * @param {string} configFile Configuration file name.
+ * @param {string} referenceId Referenced identifier to resolve.
+ * @param {Object} fs File system implementation.
  * @returns {string} Resolved path to file.
  */
-function resolveConfigExtends(configFile, referenceId) {
+function resolveConfigExtendsSync(configFile, referenceId, fs) {
   const configFileDirname = path.dirname(configFile);
   const resolvedExtendsFile = path.resolve(configFileDirname, referenceId);
   try {
-    if (fs.statSync(resolvedExtendsFile).isFile()) {
-      return resolvedExtendsFile;
-    }
+    fs.accessSync(resolvedExtendsFile);
+    return resolvedExtendsFile;
   } catch {
-    // If not a file or fs.statSync throws, try require.resolve
+    // Not a file, try require.resolve
   }
   try {
-    return require.resolve(referenceId, { "paths": [ configFileDirname ] });
+    return dynamicRequire.resolve(
+      referenceId,
+      { "paths": [ configFileDirname ] }
+    );
   } catch {
-    // If require.resolve throws, return resolvedExtendsFile
+    // Unable to resolve, return resolvedExtendsFile
   }
   return resolvedExtendsFile;
 }
@@ -949,17 +993,26 @@ function resolveConfigExtends(configFile, referenceId) {
  * @param {string} file Configuration file name.
  * @param {ConfigurationParser[] | ReadConfigCallback} parsers Parsing
  * function(s).
+ * @param {Object} [fs] File system implementation.
  * @param {ReadConfigCallback} [callback] Callback (err, result) function.
  * @returns {void}
  */
-function readConfig(file, parsers, callback) {
+function readConfig(file, parsers, fs, callback) {
   if (!callback) {
-    // @ts-ignore
-    callback = parsers;
-    parsers = null;
+    if (fs) {
+      callback = fs;
+      fs = null;
+    } else {
+      // @ts-ignore
+      callback = parsers;
+      parsers = null;
+    }
+  }
+  if (!fs) {
+    fs = require("fs");
   }
   // Read file
-  fs.readFile(file, helpers.utf8Encoding, (err, content) => {
+  fs.readFile(file, "utf8", (err, content) => {
     if (err) {
       return callback(err);
     }
@@ -973,16 +1026,25 @@ function readConfig(file, parsers, callback) {
     const configExtends = config.extends;
     if (configExtends) {
       delete config.extends;
-      const resolvedExtends = resolveConfigExtends(file, configExtends);
-      return readConfig(resolvedExtends, parsers, (errr, extendsConfig) => {
-        if (errr) {
-          return callback(errr);
-        }
-        return callback(null, {
-          ...extendsConfig,
-          ...config
-        });
-      });
+      return resolveConfigExtends(
+        file,
+        configExtends,
+        fs,
+        (_, resolvedExtends) => readConfig(
+          resolvedExtends,
+          parsers,
+          fs,
+          (errr, extendsConfig) => {
+            if (errr) {
+              return callback(errr);
+            }
+            return callback(null, {
+              ...extendsConfig,
+              ...config
+            });
+          }
+        )
+      );
     }
     return callback(null, config);
   });
@@ -995,11 +1057,12 @@ const readConfigPromisify = promisify && promisify(readConfig);
  *
  * @param {string} file Configuration file name.
  * @param {ConfigurationParser[]} [parsers] Parsing function(s).
+ * @param {Object} [fs] File system implementation.
  * @returns {Promise<Configuration>} Configuration object.
  */
-function readConfigPromise(file, parsers) {
+function readConfigPromise(file, parsers, fs) {
   // @ts-ignore
-  return readConfigPromisify(file, parsers);
+  return readConfigPromisify(file, parsers, fs);
 }
 
 /**
@@ -1007,12 +1070,16 @@ function readConfigPromise(file, parsers) {
  *
  * @param {string} file Configuration file name.
  * @param {ConfigurationParser[]} [parsers] Parsing function(s).
+ * @param {Object} [fs] File system implementation.
  * @returns {Configuration} Configuration object.
+ * @throws An Error if processing fails.
  */
-function readConfigSync(file, parsers) {
+function readConfigSync(file, parsers, fs) {
+  if (!fs) {
+    fs = require("fs");
+  }
   // Read file
-  // @ts-ignore
-  const content = fs.readFileSync(file, helpers.utf8Encoding);
+  const content = fs.readFileSync(file, "utf8");
   // Try to parse file
   const { config, message } = parseConfiguration(file, content, parsers);
   if (!config) {
@@ -1022,9 +1089,9 @@ function readConfigSync(file, parsers) {
   const configExtends = config.extends;
   if (configExtends) {
     delete config.extends;
-    const resolvedExtends = resolveConfigExtends(file, configExtends);
+    const resolvedExtends = resolveConfigExtendsSync(file, configExtends, fs);
     return {
-      ...readConfigSync(resolvedExtends, parsers),
+      ...readConfigSync(resolvedExtends, parsers, fs),
       ...config
     };
   }
@@ -1037,7 +1104,7 @@ function readConfigSync(file, parsers) {
  * @returns {string} SemVer string.
  */
 function getVersion() {
-  return require("../package.json").version;
+  return require("./constants").version;
 }
 
 // Export a/synchronous/Promise APIs
@@ -1107,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.
@@ -1131,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.
  */
 
@@ -1147,6 +1215,7 @@ module.exports = markdownlint;
  * @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.
  */
 
 /**
@@ -1188,13 +1257,14 @@ module.exports = markdownlint;
  * Fix information.
  *
  * @typedef {Object} FixInfo
+ * @property {number} [lineNumber] Line number (1-based).
  * @property {number} [editColumn] Column of the fix (1-based).
  * @property {number} [deleteCount] Count of characters to delete.
  * @property {string} [insertText] Text to insert (after deleting).
  */
 
 /**
- * Called with the result of the lint operation.
+ * Called with the result of the lint function.
  *
  * @callback LintCallback
  * @param {Error | null} err Error object or null.
@@ -1224,10 +1294,19 @@ module.exports = markdownlint;
  */
 
 /**
- * Called with the result of the readConfig operation.
+ * Called with the result of the readConfig function.
  *
  * @callback ReadConfigCallback
  * @param {Error | null} err Error object or null.
  * @param {Configuration} [config] Configuration object.
  * @returns {void}
  */
+
+/**
+ * Called with the result of the resolveConfigExtends function.
+ *
+ * @callback ResolveConfigExtendsCallback
+ * @param {Error | null} err Error object or null.
+ * @param {string} [path] Resolved path to file.
+ * @returns {void}
+ */