markdownlint 0.25.1 → 0.26.2

package/lib/markdownlint.js

@@ -20,7 +20,7 @@ const dynamicRequire = (typeof __non_webpack_require__ === "undefined") ? requir
  *
  * @param {Rule[]} ruleList List of rules.
  * @param {boolean} synchronous Whether to execute synchronously.
- * @returns {string} Error message if validation fails.
+ * @returns {Error | null} Error message if validation fails.
  */
 function validateRuleList(ruleList, synchronous) {
   let result = null;
@@ -29,32 +29,32 @@ function validateRuleList(ruleList, synchronous) {
     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 &&
@@ -76,24 +76,24 @@ function validateRuleList(ruleList, synchronous) {
       );
     }
     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;
 }
 
@@ -111,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);
@@ -129,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 });
@@ -188,15 +190,40 @@ 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) {
+function annotateAndFreezeTokens(tokens, lines) {
   let trMap = null;
-  tokens.forEach(function forToken(token) {
+  for (const token of tokens) {
     // Provide missing maps for table content
     if (token.type === "tr_open") {
       trMap = token.map;
@@ -206,11 +233,6 @@ function annotateTokens(tokens, lines) {
     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) {
       token.line = lines[token.map[0]];
@@ -219,16 +241,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")) {
@@ -236,9 +259,11 @@ function annotateTokens(tokens, lines) {
         } else if (child.type === "code_inline") {
           lineNumber += codeSpanExtraLines.shift();
         }
-      });
+      }
     }
-  });
+    freezeToken(token);
+  }
+  Object.freeze(tokens);
 }
 
 /**
@@ -250,24 +275,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 + "** - " +
@@ -292,14 +317,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)) {
@@ -309,13 +334,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.
  *
@@ -324,6 +382,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.
@@ -334,6 +393,7 @@ function getEnabledRulesPerLineNumber(
   frontMatterLines,
   noInlineConfig,
   config,
+  configParsers,
   aliasToRuleNames) {
   // Shared variables
   let enabledRules = {};
@@ -343,31 +403,36 @@ function getEnabledRulesPerLineNumber(
   // Helper functions
   // eslint-disable-next-line jsdoc/require-jsdoc
   function handleInlineConfig(input, forEachMatch, forEachLine) {
-    input.forEach((line, lineIndex) => {
+    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
       }
     }
   }
@@ -375,14 +440,13 @@ function getEnabledRulesPerLineNumber(
   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
@@ -406,9 +470,12 @@ function getEnabledRulesPerLineNumber(
     enabledRulesPerLineNumber.push(enabledRules);
   }
   // eslint-disable-next-line jsdoc/require-jsdoc
-  function disableNextLine(action, parameter, lineNumber) {
-    if (action === "DISABLE-NEXT-LINE") {
-      const nextLineNumber = frontMatterLines.length + 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,
@@ -421,15 +488,15 @@ function getEnabledRulesPerLineNumber(
   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(lines, enableDisableFile);
   handleInlineConfig(lines, captureRestoreEnableDisable, updateLineState);
-  handleInlineConfig(lines, disableNextLine);
+  handleInlineConfig(lines, disableLineNextLine);
   // Return results
   return {
     effectiveConfig,
@@ -445,6 +512,7 @@ function getEnabledRulesPerLineNumber(
  * @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.
@@ -458,6 +526,7 @@ function lintContent(
   content,
   md,
   config,
+  configParsers,
   frontMatter,
   handleRuleFailures,
   noInlineConfig,
@@ -467,42 +536,59 @@ 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 = {
-    "name": helpers.deepFreeze(name),
-    "tokens": helpers.deepFreeze(tokens),
-    "lines": helpers.deepFreeze(lines),
-    "frontMatterLines": helpers.deepFreeze(frontMatterLines)
+  // 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": Object.freeze(lines),
+    "frontMatterLines": Object.freeze(frontMatterLines)
   };
-  cache.lineMetadata(helpers.getLineMetadata(params));
-  cache.flattenedLists(helpers.flattenLists(params.tokens));
-  cache.codeBlockAndSpanRanges(
-    helpers.codeBlockAndSpanRanges(params, cache.lineMetadata())
-  );
+  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
   let results = [];
   // eslint-disable-next-line jsdoc/require-jsdoc
   function forRule(rule) {
     // Configure rule
     const ruleName = rule.names[0].toUpperCase();
-    params.config = effectiveConfig[ruleName];
+    const params = {
+      ...paramsBase,
+      "config": effectiveConfig[ruleName]
+    };
     // eslint-disable-next-line jsdoc/require-jsdoc
     function throwError(property) {
       throw new Error(
@@ -697,6 +783,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.
@@ -711,6 +798,7 @@ function lintFile(
   file,
   md,
   config,
+  configParsers,
   frontMatter,
   handleRuleFailures,
   noInlineConfig,
@@ -723,8 +811,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) {
@@ -750,7 +849,8 @@ function lintInput(options, synchronous, callback) {
   const ruleList = rules.concat(options.customRules || []);
   const ruleErr = validateRuleList(ruleList, synchronous);
   if (ruleErr) {
-    return callback(ruleErr);
+    callback(ruleErr);
+    return;
   }
   let files = [];
   if (Array.isArray(options.files)) {
@@ -761,18 +861,19 @@ 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;
@@ -804,6 +905,7 @@ function lintInput(options, synchronous, callback) {
         currentItem,
         md,
         config,
+        configParsers,
         frontMatter,
         handleRuleFailures,
         noInlineConfig,
@@ -812,16 +914,16 @@ function lintInput(options, synchronous, callback) {
         synchronous,
         lintWorkerCallback
       );
-    } else if (stringsKeys.length > 0) {
+    } else if ((currentItem = stringsKeys.shift())) {
       // Lint next string
       concurrency++;
-      currentItem = stringsKeys.shift();
       lintContent(
         ruleList,
         currentItem,
         strings[currentItem] || "",
         md,
         config,
+        configParsers,
         frontMatter,
         handleRuleFailures,
         noInlineConfig,
@@ -852,7 +954,6 @@ function lintInput(options, synchronous, callback) {
     lintWorker();
     lintWorker();
   }
-  return null;
 }
 
 /**
@@ -875,6 +976,7 @@ const markdownlintPromisify = promisify && promisify(markdownlint);
  * @returns {Promise<LintResults>} Results object.
  */
 function markdownlintPromise(options) {
+  // @ts-ignore
   return markdownlintPromisify(options);
 }
 
@@ -885,49 +987,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 = [];
-  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
-  };
-}
-
 /**
  * Resolve referenced "extends" path in a configuration file
  * using path.resolve() with require.resolve() as a fallback.
@@ -935,7 +1005,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}
  */
@@ -1005,6 +1075,7 @@ function readConfig(file, parsers, fs, callback) {
     } else {
       // @ts-ignore
       callback = parsers;
+      // @ts-ignore
       parsers = null;
     }
   }
@@ -1012,14 +1083,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
@@ -1028,16 +1103,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
@@ -1046,6 +1124,7 @@ function readConfig(file, parsers, fs, callback) {
         )
       );
     }
+    // @ts-ignore
     return callback(null, config);
   });
 }
@@ -1079,6 +1158,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);
@@ -1089,7 +1170,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
@@ -1206,16 +1291,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.
  */
 
 /**