markdownlint 0.21.0 → 0.23.1

package/helpers/helpers.js

@@ -12,12 +12,12 @@ module.exports.newLineRe = newLineRe;
 // Regular expression for matching common front matter (YAML and TOML)
 module.exports.frontMatterRe =
   // eslint-disable-next-line max-len
-  /((^---\s*$[^]*?^---\s*$)|(^\+\+\+\s*$[^]*?^(\+\+\+|\.\.\.)\s*$))(\r\n|\r|\n|$)/m;
+  /((^---\s*$[^]*?^---\s*$)|(^\+\+\+\s*$[^]*?^(\+\+\+|\.\.\.)\s*$)|(^\{\s*$[^]*?^\}\s*$))(\r\n|\r|\n|$)/m;
 
 // Regular expression for matching inline disable/enable comments
 const inlineCommentRe =
   // eslint-disable-next-line max-len
-  /<!--\s*markdownlint-(?:(?:(disable|enable|capture|restore|disable-file|enable-file)((?:\s+[a-z0-9_-]+)*))|(?:(configure-file)\s+([\s\S]*?)))\s*-->/ig;
+  /<!--\s*markdownlint-(?:(?:(disable|enable|capture|restore|disable-file|enable-file|disable-next-line)((?:\s+[a-z0-9_-]+)*))|(?:(configure-file)\s+([\s\S]*?)))\s*-->/ig;
 module.exports.inlineCommentRe = inlineCommentRe;
 
 // Regular expressions for range matching
@@ -35,7 +35,11 @@ const linkRe = /\[(?:[^[\]]|\[[^\]]*\])*\](?:\(\S*\))?/g;
 module.exports.utf8Encoding = "utf8";
 
 // All punctuation characters (normal and full-width)
-module.exports.allPunctuation = ".,;:!?。，；：！？";
+const allPunctuation = ".,;:!?。，；：！？";
+module.exports.allPunctuation = allPunctuation;
+
+// All punctuation characters without question mark (normal and full-width)
+module.exports.allPunctuationNoQuestion = allPunctuation.replace(/[?？]/gu, "");
 
 // Returns true iff the input is a number
 module.exports.isNumber = function isNumber(obj) {
@@ -61,6 +65,8 @@ module.exports.isObject = function isObject(obj) {
 // Example: Contains nothing, whitespace, or comments
 const blankLineRe = />|(?:<!--.*?-->)/g;
 module.exports.isBlankLine = function isBlankLine(line) {
+  // Call to String.replace follows best practices and is not a security check
+  // False-positive for js/incomplete-multi-character-sanitization
   return !line || !line.trim() || !line.replace(blankLineRe, "").trim();
 };
 
@@ -93,32 +99,47 @@ module.exports.includesSorted = function includesSorted(array, element) {
   return false;
 };
 
-// Replaces the text of all properly-formatted HTML comments with whitespace
+// Replaces the content of properly-formatted CommonMark comments with "."
 // This preserves the line/column information for the rest of the document
-// Trailing whitespace is avoided with a '\' character in the last column
-// See https://www.w3.org/TR/html5/syntax.html#comments for details
+// https://spec.commonmark.org/0.29/#html-blocks
+// https://spec.commonmark.org/0.29/#html-comment
 const htmlCommentBegin = "<!--";
 const htmlCommentEnd = "-->";
 module.exports.clearHtmlCommentText = function clearHtmlCommentText(text) {
   let i = 0;
   while ((i = text.indexOf(htmlCommentBegin, i)) !== -1) {
-    const j = text.indexOf(htmlCommentEnd, i);
+    const j = text.indexOf(htmlCommentEnd, i + 2);
     if (j === -1) {
       // Un-terminated comments are treated as text
       break;
     }
-    const comment = text.slice(i + htmlCommentBegin.length, j);
-    if ((comment.length > 0) &&
-        (comment[0] !== ">") &&
-        (comment[comment.length - 1] !== "-") &&
-        !comment.includes("--") &&
-        (text.slice(i, j + htmlCommentEnd.length)
-          .search(inlineCommentRe) === -1)) {
-      const blanks = comment
-        .replace(/[^\r\n]/g, " ")
-        .replace(/ ([\r\n])/g, "\\$1");
-      text = text.slice(0, i + htmlCommentBegin.length) +
-        blanks + text.slice(j);
+    // If the comment has content...
+    if (j > i + htmlCommentBegin.length) {
+      let k = i - 1;
+      while (text[k] === " ") {
+        k--;
+      }
+      // If comment is not within an indented code block...
+      if (k >= i - 4) {
+        const content = text.slice(i + htmlCommentBegin.length, j);
+        const isBlock = (k < 0) || (text[k] === "\n");
+        const isValid = isBlock ||
+          (!content.startsWith(">") && !content.startsWith("->") &&
+           !content.endsWith("-") && !content.includes("--"));
+        // If a valid block/inline comment...
+        if (isValid) {
+          const inlineCommentIndex = text
+            .slice(i, j + htmlCommentEnd.length)
+            .search(inlineCommentRe);
+          // If not a markdownlint inline directive...
+          if (inlineCommentIndex === -1) {
+            text =
+              text.slice(0, i + htmlCommentBegin.length) +
+              content.replace(/[^\r\n]/g, ".") +
+              text.slice(j);
+          }
+        }
+      }
     }
     i = j + htmlCommentEnd.length;
   }
@@ -167,7 +188,7 @@ module.exports.fencedCodeBlockStyleFor =
  */
 function indentFor(token) {
   const line = token.line.replace(/^[\s>]*(> |>)/, "");
-  return line.length - line.trimLeft().length;
+  return line.length - line.trimStart().length;
 }
 module.exports.indentFor = indentFor;
 
@@ -217,45 +238,65 @@ function filterTokens(params, type, handler) {
 }
 module.exports.filterTokens = filterTokens;
 
+/**
+ * Returns whether a token is a math block (created by markdown-it-texmath).
+ *
+ * @param {Object} token MarkdownItToken instance.
+ * @returns {boolean} True iff token is a math block.
+ */
+function isMathBlock(token) {
+  return (
+    (token.tag === "math") &&
+    token.type.startsWith("math_block") &&
+    !token.type.endsWith("_end")
+  );
+}
+
 // Get line metadata array
 module.exports.getLineMetadata = function getLineMetadata(params) {
-  const lineMetadata = params.lines.map(function mapLine(line, index) {
-    return [ line, index, false, 0, false, false ];
-  });
-  filterTokens(params, "fence", function forToken(token) {
+  const lineMetadata = params.lines.map(
+    (line, index) => [ line, index, false, 0, false, false, false, false ]
+  );
+  filterTokens(params, "fence", (token) => {
     lineMetadata[token.map[0]][3] = 1;
     lineMetadata[token.map[1] - 1][3] = -1;
     for (let i = token.map[0] + 1; i < token.map[1] - 1; i++) {
       lineMetadata[i][2] = true;
     }
   });
-  filterTokens(params, "code_block", function forToken(token) {
+  filterTokens(params, "code_block", (token) => {
     for (let i = token.map[0]; i < token.map[1]; i++) {
       lineMetadata[i][2] = true;
     }
   });
-  filterTokens(params, "table_open", function forToken(token) {
+  filterTokens(params, "table_open", (token) => {
     for (let i = token.map[0]; i < token.map[1]; i++) {
       lineMetadata[i][4] = true;
     }
   });
-  filterTokens(params, "list_item_open", function forToken(token) {
+  filterTokens(params, "list_item_open", (token) => {
     let count = 1;
     for (let i = token.map[0]; i < token.map[1]; i++) {
       lineMetadata[i][5] = count;
       count++;
     }
   });
-  filterTokens(params, "hr", function forToken(token) {
+  filterTokens(params, "hr", (token) => {
     lineMetadata[token.map[0]][6] = true;
   });
+  params.tokens.filter(isMathBlock).forEach((token) => {
+    for (let i = token.map[0]; i < token.map[1]; i++) {
+      lineMetadata[i][7] = true;
+    }
+  });
   return lineMetadata;
 };
 
 // Calls the provided function for each line (with context)
 module.exports.forEachLine = function forEachLine(lineMetadata, handler) {
   lineMetadata.forEach(function forMetadata(metadata) {
-    // Parameters: line, lineIndex, inCode, onFence, inTable, inItem, inBreak
+    // Parameters:
+    // line, lineIndex, inCode, onFence, inTable, inItem, inBreak, inMath
     handler(...metadata);
   });
 };
@@ -268,7 +309,11 @@ module.exports.flattenLists = function flattenLists(params) {
   let nesting = 0;
   const nestingStack = [];
   let lastWithMap = { "map": [ 0, 1 ] };
-  params.tokens.forEach(function forToken(token) {
+  params.tokens.forEach((token) => {
+    if (isMathBlock(token) && token.map[1]) {
+      // markdown-it-texmath plugin does not account for math_block_end
+      token.map[1]++;
+    }
     if ((token.type === "bullet_list_open") ||
         (token.type === "ordered_list_open")) {
       // Save current context and start a new one
@@ -355,6 +400,7 @@ function forEachInlineCodeSpan(input, handler) {
     let currentTicks = 0;
     let state = "normal";
     // Deliberate <= so trailing 0 completes the last span (ex: "text `code`")
+    // False-positive for js/index-out-of-bounds
     for (; index <= input.length; index++) {
       const char = input[index];
       // Ignore backticks in link destination
@@ -491,7 +537,10 @@ module.exports.frontMatterHasTitle =
     const ignoreFrontMatter =
       (frontMatterTitlePattern !== undefined) && !frontMatterTitlePattern;
     const frontMatterTitleRe =
-      new RegExp(String(frontMatterTitlePattern || "^\\s*title\\s*[:=]"), "i");
+      new RegExp(
+        String(frontMatterTitlePattern || "^\\s*\"?title\"?\\s*[:=]"),
+        "i"
+      );
     return !ignoreFrontMatter &&
       frontMatterLines.some((line) => frontMatterTitleRe.test(line));
   };
@@ -674,8 +723,9 @@ module.exports.applyFixes = function applyFixes(input, errors) {
     const editIndex = editColumn - 1;
     if (
       (lineIndex !== lastLineIndex) ||
-      ((editIndex + deleteCount) < lastEditIndex) ||
-      (deleteCount === -1)
+      (deleteCount === -1) ||
+      ((editIndex + deleteCount) <=
+        (lastEditIndex - ((deleteCount > 0) ? 0 : 1)))
     ) {
       lines[lineIndex] = applyFix(lines[lineIndex], fixInfo, lineEnding);
     }

package/helpers/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markdownlint-rule-helpers",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "A collection of markdownlint helper functions for custom rules",
   "main": "helpers.js",
   "author": "David Anson (https://dlaa.me/)",

package/lib/markdownlint.d.ts

@@ -8,7 +8,7 @@ export = markdownlint;
  */
 declare function markdownlint(options: Options, callback: LintCallback): void;
 declare namespace markdownlint {
-    export { markdownlintSync as sync, readConfig, readConfigSync, promises, RuleFunction, RuleParams, MarkdownItToken, RuleOnError, RuleOnErrorInfo, RuleOnErrorFixInfo, Rule, Options, Plugin, ToStringCallback, LintResults, LintError, FixInfo, LintCallback, Configuration, RuleConfiguration, ConfigurationParser, ReadConfigCallback };
+    export { markdownlintSync as sync, readConfig, readConfigSync, getVersion, promises, RuleFunction, RuleParams, MarkdownItToken, RuleOnError, RuleOnErrorInfo, RuleOnErrorFixInfo, Rule, Options, Plugin, ToStringCallback, LintResults, LintError, FixInfo, LintCallback, Configuration, RuleConfiguration, ConfigurationParser, ReadConfigCallback };
 }
 /**
  * Configuration options.
@@ -51,7 +51,7 @@ type Options = {
     /**
      * Additional plugins.
      */
-    markdownItPlugins?: any[][];
+    markdownItPlugins?: Plugin[];
 };
 /**
  * Called with the result of the lint operation.
@@ -82,6 +82,12 @@ declare function readConfig(file: string, parsers: ConfigurationParser[] | ReadC
  * @returns {Configuration} Configuration object.
  */
 declare function readConfigSync(file: string, parsers?: ConfigurationParser[]): Configuration;
+/**
+ * Gets the (semantic) version of the library.
+ *
+ * @returns {string} SemVer string.
+ */
+declare function getVersion(): string;
 declare namespace promises {
     export { markdownlintPromise as markdownlint };
     export { readConfigPromise as readConfig };
@@ -99,7 +105,7 @@ type RuleParams = {
      */
     name: string;
     /**
-     * markdown-it token objects.
+     * Token objects from markdown-it.
      */
     tokens: MarkdownItToken[];
     /**
@@ -256,7 +262,7 @@ type Rule = {
     function: RuleFunction;
 };
 /**
- * markdown-it plugin.
+ * A markdown-it plugin.
  */
 type Plugin = any[];
 /**
@@ -304,7 +310,7 @@ type LintError = {
     /**
      * Fix information.
      */
-    fixInfo: FixInfo;
+    fixInfo?: FixInfo;
 };
 /**
  * Fix information.

package/lib/markdownlint.js

@@ -4,12 +4,17 @@
 
 const fs = require("fs");
 const path = require("path");
-const util = require("util");
+const { promisify } = require("util");
 const markdownIt = require("markdown-it");
 const rules = require("./rules");
 const helpers = require("../helpers");
 const cache = require("./cache");
 
+// @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
+
 const deprecatedRuleNames = [ "MD002", "MD006" ];
 
 /**
@@ -51,10 +56,12 @@ function validateRuleList(ruleList) {
         result = newError(property);
       }
     });
-    if (!result && rule.information) {
-      if (Object.getPrototypeOf(rule.information) !== URL.prototype) {
-        result = newError("information");
-      }
+    if (
+      !result &&
+      rule.information &&
+      (Object.getPrototypeOf(rule.information) !== URL.prototype)
+    ) {
+      result = newError("information");
     }
     if (!result) {
       rule.names.forEach(function forName(name) {
@@ -176,18 +183,27 @@ function removeFrontMatter(content, frontMatter) {
  * @returns {void}
  */
 function annotateTokens(tokens, lines) {
-  let tbodyMap = null;
+  let tableMap = null;
   tokens.forEach(function forToken(token) {
-    // Handle missing maps for table body
-    if (token.type === "tbody_open") {
-      tbodyMap = token.map.slice();
-    } else if ((token.type === "tr_close") && tbodyMap) {
-      tbodyMap[0]++;
-    } else if (token.type === "tbody_close") {
-      tbodyMap = null;
+    // 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;
     }
-    if (tbodyMap && !token.map) {
-      token.map = tbodyMap.slice();
+    if (tableMap && !token.map) {
+      token.map = tableMap.slice();
     }
     // Update token metadata
     if (token.map) {
@@ -322,13 +338,13 @@ function getEnabledRulesPerLineNumber(
   // eslint-disable-next-line jsdoc/require-jsdoc
   function handleInlineConfig(perLine, forEachMatch, forEachLine) {
     const input = perLine ? lines : [ lines.join("\n") ];
-    input.forEach((line) => {
+    input.forEach((line, lineIndex) => {
       if (!noInlineConfig) {
         let match = null;
         while ((match = helpers.inlineCommentRe.exec(line))) {
           const action = (match[1] || match[3]).toUpperCase();
           const parameter = match[2] || match[4];
-          forEachMatch(action, parameter);
+          forEachMatch(action, parameter, lineIndex + 1);
         }
       }
       if (forEachLine) {
@@ -345,28 +361,27 @@ function getEnabledRulesPerLineNumber(
           ...config,
           ...json
         };
-      // eslint-disable-next-line unicorn/prefer-optional-catch-binding
-      } catch (error) {
+      } catch {
         // Ignore parse errors for inline configuration
       }
     }
   }
   // eslint-disable-next-line jsdoc/require-jsdoc
-  function applyEnableDisable(action, parameter) {
+  function applyEnableDisable(action, parameter, state) {
     const enabled = (action.startsWith("ENABLE"));
     const items = parameter ?
       parameter.trim().toUpperCase().split(/\s+/) :
       allRuleNames;
     items.forEach((nameUpper) => {
       (aliasToRuleNames[nameUpper] || []).forEach((ruleName) => {
-        enabledRules[ruleName] = enabled;
+        state[ruleName] = enabled;
       });
     });
   }
   // eslint-disable-next-line jsdoc/require-jsdoc
   function enableDisableFile(action, parameter) {
     if ((action === "ENABLE-FILE") || (action === "DISABLE-FILE")) {
-      applyEnableDisable(action, parameter);
+      applyEnableDisable(action, parameter, enabledRules);
     }
   }
   // eslint-disable-next-line jsdoc/require-jsdoc
@@ -377,12 +392,22 @@ function getEnabledRulesPerLineNumber(
       enabledRules = { ...capturedRules };
     } else if ((action === "ENABLE") || (action === "DISABLE")) {
       enabledRules = { ...enabledRules };
-      applyEnableDisable(action, parameter);
+      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] || {}
+      );
+    }
   }
   // Handle inline comments
   handleInlineConfig(false, configureFile);
@@ -396,6 +421,7 @@ function getEnabledRulesPerLineNumber(
   capturedRules = enabledRules;
   handleInlineConfig(true, enableDisableFile);
   handleInlineConfig(true, captureRestoreEnableDisable, updateLineState);
+  handleInlineConfig(true, disableNextLine);
   // Return results
   return {
     effectiveConfig,
@@ -440,8 +466,8 @@ function uniqueFilterForSortedErrors(value, index, array) {
  *
  * @param {Rule[]} ruleList List of rules.
  * @param {string} name Identifier for the content.
- * @param {string} content Markdown content
- * @param {Object} md markdown-it instance.
+ * @param {string} content Markdown content.
+ * @param {Object} md Instance of markdown-it.
  * @param {Configuration} config Configuration object.
  * @param {RegExp} frontMatter Regular expression for front matter.
  * @param {boolean} handleRuleFailures Whether to handle exceptions in rules.
@@ -652,7 +678,7 @@ function lintContent(
  *
  * @param {Rule[]} ruleList List of rules.
  * @param {string} file Path of file to lint.
- * @param {Object} md markdown-it instance.
+ * @param {Object} md Instance of markdown-it.
  * @param {Configuration} config Configuration object.
  * @param {RegExp} frontMatter Regular expression for front matter.
  * @param {boolean} handleRuleFailures Whether to handle exceptions in rules.
@@ -702,6 +728,7 @@ function lintInput(options, synchronous, callback) {
   // Normalize inputs
   options = options || {};
   callback = callback || function noop() {};
+  // eslint-disable-next-line unicorn/prefer-spread
   const ruleList = rules.concat(options.customRules || []);
   const ruleErr = validateRuleList(ruleList);
   if (ruleErr) {
@@ -834,7 +861,7 @@ function markdownlint(options, callback) {
   return lintInput(options, false, callback);
 }
 
-const markdownlintPromisify = util.promisify(markdownlint);
+const markdownlintPromisify = promisify && promisify(markdownlint);
 
 /**
  * Lint specified Markdown files.
@@ -895,6 +922,35 @@ function parseConfiguration(name, content, parsers) {
   };
 }
 
+/**
+ * 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.
+ * @returns {string} Resolved path to file.
+ */
+function resolveConfigExtends(configFile, referenceId) {
+  const configFileDirname = path.dirname(configFile);
+  const resolvedExtendsFile = path.resolve(configFileDirname, referenceId);
+  try {
+    if (fs.statSync(resolvedExtendsFile).isFile()) {
+      return resolvedExtendsFile;
+    }
+  } catch {
+    // If not a file or fs.statSync throws, try require.resolve
+  }
+  try {
+    return dynamicRequire.resolve(
+      referenceId,
+      { "paths": [ configFileDirname ] }
+    );
+  } catch {
+    // If require.resolve throws, return resolvedExtendsFile
+  }
+  return resolvedExtendsFile;
+}
+
 /**
  * Read specified configuration file.
  *
@@ -925,8 +981,8 @@ function readConfig(file, parsers, callback) {
     const configExtends = config.extends;
     if (configExtends) {
       delete config.extends;
-      const extendsFile = path.resolve(path.dirname(file), configExtends);
-      return readConfig(extendsFile, parsers, (errr, extendsConfig) => {
+      const resolvedExtends = resolveConfigExtends(file, configExtends);
+      return readConfig(resolvedExtends, parsers, (errr, extendsConfig) => {
         if (errr) {
           return callback(errr);
         }
@@ -940,7 +996,7 @@ function readConfig(file, parsers, callback) {
   });
 }
 
-const readConfigPromisify = util.promisify(readConfig);
+const readConfigPromisify = promisify && promisify(readConfig);
 
 /**
  * Read specified configuration file.
@@ -974,21 +1030,29 @@ function readConfigSync(file, parsers) {
   const configExtends = config.extends;
   if (configExtends) {
     delete config.extends;
+    const resolvedExtends = resolveConfigExtends(file, configExtends);
     return {
-      ...readConfigSync(
-        path.resolve(path.dirname(file), configExtends),
-        parsers
-      ),
+      ...readConfigSync(resolvedExtends, parsers),
       ...config
     };
   }
   return config;
 }
 
+/**
+ * Gets the (semantic) version of the library.
+ *
+ * @returns {string} SemVer string.
+ */
+function getVersion() {
+  return require("../package.json").version;
+}
+
 // Export a/synchronous/Promise APIs
 markdownlint.sync = markdownlintSync;
 markdownlint.readConfig = readConfig;
 markdownlint.readConfigSync = readConfigSync;
+markdownlint.getVersion = getVersion;
 markdownlint.promises = {
   "markdownlint": markdownlintPromise,
   "readConfig": readConfigPromise
@@ -1011,7 +1075,7 @@ module.exports = markdownlint;
  *
  * @typedef {Object} RuleParams
  * @property {string} name File/string name.
- * @property {MarkdownItToken[]} tokens markdown-it token objects.
+ * @property {MarkdownItToken[]} tokens Token objects from markdown-it.
  * @property {string[]} lines File/string lines.
  * @property {string[]} frontMatterLines Front matter lines.
  * @property {RuleConfiguration} config Rule configuration.
@@ -1094,7 +1158,7 @@ module.exports = markdownlint;
  */
 
 /**
- * markdown-it plugin.
+ * A markdown-it plugin.
  *
  * @typedef {Array} Plugin
  */
@@ -1125,7 +1189,7 @@ module.exports = markdownlint;
  * @property {string} errorDetail Detail about the error.
  * @property {string} errorContext Context for the error.
  * @property {number[]} errorRange Column number (1-based) and length.
- * @property {FixInfo} fixInfo Fix information.
+ * @property {FixInfo} [fixInfo] Fix information.
  */
 
 /**

package/lib/md002.js

@@ -6,7 +6,7 @@ const { addErrorDetailIf } = require("../helpers");
 
 module.exports = {
   "names": [ "MD002", "first-heading-h1", "first-header-h1" ],
-  "description": "First heading should be a top level heading",
+  "description": "First heading should be a top-level heading",
   "tags": [ "headings", "headers" ],
   "function": function MD002(params, onError) {
     const level = Number(params.config.level || 1);