markdownlint 0.26.2 → 0.28.0

package/helpers/micromark.cjs

@@ -0,0 +1,209 @@
+// @ts-check
+
+"use strict";
+
+// @ts-ignore
+const {
+  gfmAutolinkLiteral, gfmFootnote, gfmTable, parse, postprocess, preprocess
+  // @ts-ignore
+} = require("markdownlint-micromark");
+
+/**
+ * Markdown token.
+ *
+ * @typedef {Object} Token
+ * @property {string} type Token type.
+ * @property {number} startLine Start line (1-based).
+ * @property {number} startColumn Start column (1-based).
+ * @property {number} endLine End line (1-based).
+ * @property {number} endColumn End column (1-based).
+ * @property {string} text Token text.
+ * @property {Token[]} children Child tokens.
+ */
+
+/**
+ * Parses a Markdown document and returns Micromark events.
+ *
+ * @param {string} markdown Markdown document.
+ * @param {Object} [options] Options for micromark.
+ * @returns {Object[]} Micromark events.
+ */
+function getMicromarkEvents(markdown, options = {}) {
+
+  // Customize options object to add useful extensions
+  options.extensions = options.extensions || [];
+  options.extensions.push(gfmAutolinkLiteral, gfmFootnote(), gfmTable);
+
+  // Use micromark to parse document into Events
+  const encoding = undefined;
+  const eol = true;
+  const parseContext = parse(options);
+  // Customize ParseContext to treat all references as defined
+  parseContext.defined.includes = (searchElement) => searchElement.length > 0;
+  const chunks = preprocess()(markdown, encoding, eol);
+  const events = postprocess(parseContext.document().write(chunks));
+  return events;
+}
+
+/**
+ * Parses a Markdown document and returns (frozen) tokens.
+ *
+ * @param {string} markdown Markdown document.
+ * @param {Object} [options] Options for micromark.
+ * @returns {Token[]} Micromark tokens (frozen).
+ */
+function micromarkParse(markdown, options = {}) {
+
+  // Use micromark to parse document into Events
+  const events = getMicromarkEvents(markdown, options);
+
+  // Create Token objects
+  const document = [];
+  let current = {
+    "children": document
+  };
+  const history = [ current ];
+  for (const event of events) {
+    const [ kind, token, context ] = event;
+    const { type, start, end } = token;
+    const { "column": startColumn, "line": startLine } = start;
+    const { "column": endColumn, "line": endLine } = end;
+    let text = null;
+    try {
+      text = context.sliceSerialize(token);
+    } catch {
+      // https://github.com/micromark/micromark/issues/131
+    }
+    if (kind === "enter") {
+      const previous = current;
+      history.push(previous);
+      current = {
+        type,
+        startLine,
+        startColumn,
+        endLine,
+        endColumn,
+        text,
+        "children": []
+      };
+      previous.children.push(current);
+    } else if (kind === "exit") {
+      Object.freeze(current.children);
+      Object.freeze(current);
+      // @ts-ignore
+      current = history.pop();
+    }
+  }
+
+  // Return document
+  Object.freeze(document);
+  return document;
+}
+
+/**
+ * Filter a list of Micromark tokens by predicate.
+ *
+ * @param {Token[]} tokens Micromark tokens.
+ * @param {Function} allowed Allowed token predicate.
+ * @param {Function} [transformChildren] Transform children predicate.
+ * @returns {Token[]} Filtered tokens.
+ */
+function filterByPredicate(tokens, allowed, transformChildren) {
+  const result = [];
+  const pending = [ ...tokens ];
+  let token = null;
+  while ((token = pending.shift())) {
+    if (allowed(token)) {
+      result.push(token);
+    }
+    if (token.children.length > 0) {
+      const transformed =
+        transformChildren ? transformChildren(token) : token.children;
+      pending.unshift(...transformed);
+    }
+  }
+  return result;
+}
+
+/**
+ * Filter a list of Micromark tokens by type.
+ *
+ * @param {Token[]} tokens Micromark tokens.
+ * @param {string[]} allowed Types to allow.
+ * @returns {Token[]} Filtered tokens.
+ */
+function filterByTypes(tokens, allowed) {
+  return filterByPredicate(
+    tokens,
+    (token) => allowed.includes(token.type)
+  );
+}
+
+/**
+ * Gets information about the tag in an HTML token.
+ *
+ * @param {Token} token Micromark token.
+ * @returns {Object | null} HTML tag information.
+ */
+function getHtmlTagInfo(token) {
+  const htmlTagNameRe = /^<([^!>][^/\s>]*)/;
+  if (token.type === "htmlText") {
+    const match = htmlTagNameRe.exec(token.text);
+    if (match) {
+      const name = match[1];
+      const close = name.startsWith("/");
+      return {
+        close,
+        "name": close ? name.slice(1) : name
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Get the text of a single token from a list of Micromark tokens by type.
+ *
+ * @param {Token[]} tokens Micromark tokens.
+ * @param {string} type Types to match.
+ * @returns {string | null} Text of token.
+ */
+function getTokenTextByType(tokens, type) {
+  const filtered = tokens.filter((token) => token.type === type);
+  return (filtered.length === 1) ? filtered[0].text : null;
+}
+
+/**
+ * Determines a list of Micromark tokens matches and returns a subset.
+ *
+ * @param {Token[]} tokens Micromark tokens.
+ * @param {string[]} matchTypes Types to match.
+ * @param {string[]} [resultTypes] Types to return.
+ * @returns {Token[] | null} Matching tokens.
+ */
+function matchAndGetTokensByType(tokens, matchTypes, resultTypes) {
+  if (tokens.length !== matchTypes.length) {
+    return null;
+  }
+  resultTypes = resultTypes || matchTypes;
+  const result = [];
+  // eslint-disable-next-line unicorn/no-for-loop
+  for (let i = 0; i < matchTypes.length; i++) {
+    if (tokens[i].type !== matchTypes[i]) {
+      return null;
+    } else if (resultTypes.includes(matchTypes[i])) {
+      result.push(tokens[i]);
+    }
+  }
+  return result;
+}
+
+module.exports = {
+  "parse": micromarkParse,
+  filterByPredicate,
+  filterByTypes,
+  getHtmlTagInfo,
+  getMicromarkEvents,
+  getTokenTextByType,
+  matchAndGetTokensByType
+};

package/helpers/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markdownlint-rule-helpers",
-  "version": "0.17.2",
+  "version": "0.19.0",
   "description": "A collection of markdownlint helper functions for custom rules",
   "main": "./helpers.js",
   "exports": "./helpers.js",
@@ -13,7 +13,10 @@
   },
   "bugs": "https://github.com/DavidAnson/markdownlint/issues",
   "engines": {
-    "node": ">=12"
+    "node": ">=14.18.0"
+  },
+  "dependencies": {
+    "markdownlint-micromark": "0.1.2"
   },
   "keywords": [
     "markdownlint",

package/lib/constants.js

@@ -3,5 +3,12 @@
 "use strict";
 
 module.exports.deprecatedRuleNames = [ "MD002", "MD006" ];
+module.exports.fixableRuleNames = [
+  "MD004", "MD005", "MD006", "MD007", "MD009", "MD010",
+  "MD011", "MD012", "MD014", "MD018", "MD019", "MD020",
+  "MD021", "MD022", "MD023", "MD026", "MD027", "MD030",
+  "MD031", "MD032", "MD034", "MD037", "MD038", "MD039",
+  "MD044", "MD047", "MD049", "MD050", "MD051", "MD053"
+];
 module.exports.homepage = "https://github.com/DavidAnson/markdownlint";
-module.exports.version = "0.26.2";
+module.exports.version = "0.28.0";

package/lib/markdownlint.d.ts

@@ -2,11 +2,11 @@ export = markdownlint;
 /**
  * Lint specified Markdown files.
  *
- * @param {Options} options Configuration options.
+ * @param {Options | null} options Configuration options.
  * @param {LintCallback} callback Callback (err, result) function.
  * @returns {void}
  */
-declare function markdownlint(options: Options, callback: LintCallback): void;
+declare function markdownlint(options: Options | null, callback: LintCallback): void;
 declare namespace markdownlint {
     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, ResolveConfigExtendsCallback };
 }
@@ -33,7 +33,7 @@ type Options = {
     /**
      * Front matter pattern.
      */
-    frontMatter?: RegExp;
+    frontMatter?: RegExp | null;
     /**
      * File system implementation.
      */
@@ -68,10 +68,10 @@ type LintCallback = (err: Error | null, results?: LintResults) => void;
 /**
  * Lint specified Markdown files synchronously.
  *
- * @param {Options} options Configuration options.
+ * @param {Options | null} options Configuration options.
  * @returns {LintResults} Results object.
  */
-declare function markdownlintSync(options: Options): LintResults;
+declare function markdownlintSync(options: Options | null): LintResults;
 /**
  * Read specified configuration file.
  *

package/lib/markdownlint.js

@@ -2,9 +2,10 @@
 
 "use strict";
 
-const path = require("path");
-const { promisify } = require("util");
-const markdownIt = require("markdown-it");
+const path = require("node:path");
+const { promisify } = require("node:util");
+const markdownit = require("markdown-it");
+const micromark = require("../helpers/micromark.cjs");
 const { deprecatedRuleNames } = require("./constants");
 const rules = require("./rules");
 const helpers = require("../helpers");
@@ -166,7 +167,7 @@ function newResults(ruleList) {
  * Remove front matter (if present at beginning of content).
  *
  * @param {string} content Markdown content.
- * @param {RegExp} frontMatter Regular expression to match front matter.
+ * @param {RegExp | null} frontMatter Regular expression to match front matter.
  * @returns {Object} Trimmed content and front matter lines.
  */
 function removeFrontMatter(content, frontMatter) {
@@ -508,12 +509,14 @@ function getEnabledRulesPerLineNumber(
  * Lints a string containing Markdown content.
  *
  * @param {Rule[]} ruleList List of rules.
+ * @param {Object.<string, string[]>} aliasToRuleNames Map of alias to rule
+ * names.
  * @param {string} name Identifier for the content.
  * @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 {RegExp | null} frontMatter Regular expression for front matter.
  * @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.
@@ -522,6 +525,7 @@ function getEnabledRulesPerLineNumber(
  */
 function lintContent(
   ruleList,
+  aliasToRuleNames,
   name,
   content,
   md,
@@ -547,18 +551,29 @@ function lintContent(
       noInlineConfig,
       config,
       configParsers,
-      mapAliasToRuleNames(ruleList)
+      aliasToRuleNames
     );
-  // Hide the content of HTML comments from rules, etc.
+  // Parse content into parser tokens
+  const markdownitTokens = md.parse(content, {});
+  const micromarkTokens = micromark.parse(content);
+  // Hide the content of HTML comments from rules
   content = helpers.clearHtmlCommentText(content);
-  // Parse content into tokens and lines
-  const tokens = md.parse(content, {});
+  // Parse content into lines and update markdown-it tokens
   const lines = content.split(helpers.newLineRe);
-  annotateAndFreezeTokens(tokens, lines);
+  annotateAndFreezeTokens(markdownitTokens, lines);
   // Create (frozen) parameters for rules
+  const parsers = Object.freeze({
+    "markdownit": Object.freeze({
+      "tokens": markdownitTokens
+    }),
+    "micromark": Object.freeze({
+      "tokens": micromarkTokens
+    })
+  });
   const paramsBase = {
     name,
-    tokens,
+    parsers,
+    "tokens": markdownitTokens,
     "lines": Object.freeze(lines),
     "frontMatterLines": Object.freeze(frontMatterLines)
   };
@@ -567,11 +582,11 @@ function lintContent(
   const codeBlockAndSpanRanges =
     helpers.codeBlockAndSpanRanges(paramsBase, lineMetadata);
   const flattenedLists =
-    helpers.flattenLists(paramsBase.tokens);
+    helpers.flattenLists(paramsBase.parsers.markdownit.tokens);
   const htmlElementRanges =
     helpers.htmlElementRanges(paramsBase, lineMetadata);
   const referenceLinkImageData =
-    helpers.getReferenceLinkImageData(lineMetadata);
+    helpers.getReferenceLinkImageData(paramsBase);
   cache.set({
     codeBlockAndSpanRanges,
     flattenedLists,
@@ -780,11 +795,13 @@ function lintContent(
  * Lints a file containing Markdown content.
  *
  * @param {Rule[]} ruleList List of rules.
+ * @param {Object.<string, string[]>} aliasToRuleNames Map of alias to rule
+ * names.
  * @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 {RegExp | null} frontMatter Regular expression for front matter.
  * @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.
@@ -795,6 +812,7 @@ function lintContent(
  */
 function lintFile(
   ruleList,
+  aliasToRuleNames,
   file,
   md,
   config,
@@ -813,6 +831,7 @@ function lintFile(
     }
     return lintContent(
       ruleList,
+      aliasToRuleNames,
       file,
       content,
       md,
@@ -836,7 +855,7 @@ function lintFile(
 /**
  * Lint files and strings specified in the Options object.
  *
- * @param {Options} options Options object.
+ * @param {Options | null} options Options object.
  * @param {boolean} synchronous Whether to execute synchronously.
  * @param {Function} callback Callback (err, result) function.
  * @returns {void}
@@ -868,13 +887,14 @@ function lintInput(options, synchronous, callback) {
   const noInlineConfig = !!options.noInlineConfig;
   const resultVersion = (options.resultVersion === undefined) ?
     3 : options.resultVersion;
-  const md = markdownIt({ "html": true });
+  const md = markdownit({ "html": true });
   const markdownItPlugins = options.markdownItPlugins || [];
   for (const plugin of markdownItPlugins) {
     // @ts-ignore
     md.use(...plugin);
   }
-  const fs = options.fs || require("fs");
+  const fs = options.fs || require("node:fs");
+  const aliasToRuleNames = mapAliasToRuleNames(ruleList);
   const results = newResults(ruleList);
   let done = false;
   let concurrency = 0;
@@ -902,6 +922,7 @@ function lintInput(options, synchronous, callback) {
       currentItem = files.shift();
       lintFile(
         ruleList,
+        aliasToRuleNames,
         currentItem,
         md,
         config,
@@ -919,6 +940,7 @@ function lintInput(options, synchronous, callback) {
       concurrency++;
       lintContent(
         ruleList,
+        aliasToRuleNames,
         currentItem,
         strings[currentItem] || "",
         md,
@@ -959,7 +981,7 @@ function lintInput(options, synchronous, callback) {
 /**
  * Lint specified Markdown files.
  *
- * @param {Options} options Configuration options.
+ * @param {Options | null} options Configuration options.
  * @param {LintCallback} callback Callback (err, result) function.
  * @returns {void}
  */
@@ -983,7 +1005,7 @@ function markdownlintPromise(options) {
 /**
  * Lint specified Markdown files synchronously.
  *
- * @param {Options} options Configuration options.
+ * @param {Options | null} options Configuration options.
  * @returns {LintResults} Results object.
  */
 function markdownlintSync(options) {
@@ -1080,10 +1102,10 @@ function readConfig(file, parsers, fs, callback) {
     }
   }
   if (!fs) {
-    fs = require("fs");
+    fs = require("node:fs");
   }
   // Read file
-  const os = require("os");
+  const os = require("node:os");
   file = helpers.expandTildePath(file, os);
   fs.readFile(file, "utf8", (err, content) => {
     if (err) {
@@ -1155,10 +1177,10 @@ function readConfigPromise(file, parsers, fs) {
  */
 function readConfigSync(file, parsers, fs) {
   if (!fs) {
-    fs = require("fs");
+    fs = require("node:fs");
   }
   // Read file
-  const os = require("os");
+  const os = require("node:os");
   file = helpers.expandTildePath(file, os);
   const content = fs.readFileSync(file, "utf8");
   // Try to parse file
@@ -1295,7 +1317,7 @@ module.exports = markdownlint;
  * @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 {RegExp | null} [frontMatter] Front matter pattern.
  * @property {Object} [fs] File system implementation.
  * @property {boolean} [handleRuleFailures] True to catch exceptions.
  * @property {Plugin[]} [markdownItPlugins] Additional plugins.

package/lib/md002.js

@@ -11,7 +11,7 @@ module.exports = {
   "function": function MD002(params, onError) {
     const level = Number(params.config.level || 1);
     const tag = "h" + level;
-    params.tokens.every(function forToken(token) {
+    params.parsers.markdownit.tokens.every(function forToken(token) {
       if (token.type === "heading_open") {
         addErrorDetailIf(onError, token.lineNumber, tag, token.tag);
         return false;

package/lib/md011.js

@@ -6,7 +6,7 @@ const { addError, forEachLine, withinAnyRange } = require("../helpers");
 const { codeBlockAndSpanRanges, lineMetadata } = require("./cache");
 
 const reversedLinkRe =
-  /(^|[^\\])\(([^)]+)\)\[([^\]^][^\]]*)](?!\()/g;
+  /(^|[^\\])\(([^()]+)\)\[([^\]^][^\]]*)\](?!\()/g;
 
 module.exports = {
   "names": [ "MD011", "no-reversed-links" ],
@@ -30,7 +30,7 @@ module.exports = {
               onError,
               lineIndex + 1,
               reversedLink.slice(preChar.length),
-              null,
+              undefined,
               [ index + 1, length ],
               {
                 "editColumn": index + 1,

package/lib/md013.js

@@ -3,14 +3,14 @@
 "use strict";
 
 const { addErrorDetailIf, filterTokens, forEachHeading, forEachLine,
-  includesSorted, linkReferenceDefinitionRe } = require("../helpers");
-const { lineMetadata } = require("./cache");
+  includesSorted } = require("../helpers");
+const { lineMetadata, referenceLinkImageData } = require("./cache");
 
 const longLineRePrefix = "^.{";
 const longLineRePostfixRelaxed = "}.*\\s.*$";
 const longLineRePostfixStrict = "}.+$";
-const linkOrImageOnlyLineRe = /^[es]*(lT?L|I)[ES]*$/;
-const sternModeRe = /^([#>\s]*\s)?\S*$/;
+const linkOrImageOnlyLineRe = /^[es]*(?:lT?L|I)[ES]*$/;
+const sternModeRe = /^(?:[#>\s]*\s)?\S*$/;
 const tokenTypeMap = {
   "em_open": "e",
   "em_close": "E",
@@ -67,6 +67,7 @@ module.exports = {
         linkOnlyLineNumbers.push(token.lineNumber);
       }
     });
+    const { definitionLineIndices } = referenceLinkImageData();
     forEachLine(lineMetadata(), (line, lineIndex, inCode, onFence, inTable) => {
       const lineNumber = lineIndex + 1;
       const isHeading = includesSorted(headingLineNumbers, lineNumber);
@@ -79,10 +80,10 @@ module.exports = {
       if ((includeCodeBlocks || !inCode) &&
           (includeTables || !inTable) &&
           (includeHeadings || !isHeading) &&
+          !includesSorted(definitionLineIndices, lineIndex) &&
           (strict ||
            (!(stern && sternModeRe.test(line)) &&
-            !includesSorted(linkOnlyLineNumbers, lineNumber) &&
-            !linkReferenceDefinitionRe.test(line))) &&
+            !includesSorted(linkOnlyLineNumbers, lineNumber))) &&
           lengthRe.test(line)) {
         addErrorDetailIf(
           onError,

package/lib/md019.js

@@ -13,7 +13,7 @@ module.exports = {
     filterTokens(params, "heading_open", (token) => {
       if (headingStyleFor(token) === "atx") {
         const { line, lineNumber } = token;
-        const match = /^(#+)([ \t]{2,})(?:\S)/.exec(line);
+        const match = /^(#+)([ \t]{2,})\S/.exec(line);
         if (match) {
           const [
             ,

package/lib/md022.js

@@ -2,7 +2,17 @@
 
 "use strict";
 
-const { addErrorDetailIf, filterTokens, isBlankLine } = require("../helpers");
+const { addErrorDetailIf, blockquotePrefixRe, filterTokens, isBlankLine } =
+  require("../helpers");
+
+const getBlockQuote = (str, count) => (
+  (str || "")
+    .match(blockquotePrefixRe)[0]
+    .trimEnd()
+    // eslint-disable-next-line unicorn/prefer-spread
+    .concat("\n")
+    .repeat(count)
+);
 
 module.exports = {
   "names": [ "MD022", "blanks-around-headings", "blanks-around-headers" ],
@@ -31,7 +41,8 @@ module.exports = {
         lines[topIndex].trim(),
         null,
         {
-          "insertText": "".padEnd(linesAbove - actualAbove, "\n")
+          "insertText":
+            getBlockQuote(lines[topIndex - 1], linesAbove - actualAbove)
         });
       let actualBelow = 0;
       for (let i = 0; i < linesBelow; i++) {
@@ -49,7 +60,8 @@ module.exports = {
         null,
         {
           "lineNumber": nextIndex + 1,
-          "insertText": "".padEnd(linesBelow - actualBelow, "\n")
+          "insertText":
+            getBlockQuote(lines[nextIndex], linesBelow - actualBelow)
         });
     });
   }

package/lib/md023.js

@@ -4,7 +4,7 @@
 
 const { addErrorContext, filterTokens } = require("../helpers");
 
-const spaceBeforeHeadingRe = /^((?:\s+)|(?:[>\s]+\s\s))[^>\s]/;
+const spaceBeforeHeadingRe = /^(\s+|[>\s]+\s\s)[^>\s]/;
 
 module.exports = {
   "names": [ "MD023", "heading-start-left", "header-start-left" ],

package/lib/md026.js

@@ -5,7 +5,7 @@
 const { addError, allPunctuationNoQuestion, escapeForRegExp, forEachHeading } =
   require("../helpers");
 
-const endOfLineHtmlEntityRe = /&#?[0-9a-zA-Z]+;$/;
+const endOfLineHtmlEntityRe = /&#?[\da-zA-Z]+;$/;
 
 module.exports = {
   "names": [ "MD026", "no-trailing-punctuation" ],

package/lib/md027.js

@@ -13,7 +13,7 @@ module.exports = {
   "function": function MD027(params, onError) {
     let blockquoteNesting = 0;
     let listItemNesting = 0;
-    for (const token of params.tokens) {
+    for (const token of params.parsers.markdownit.tokens) {
       const { content, lineNumber, type } = token;
       if (type === "blockquote_open") {
         blockquoteNesting++;

package/lib/md028.js

@@ -11,7 +11,7 @@ module.exports = {
   "function": function MD028(params, onError) {
     let prevToken = {};
     let prevLineNumber = null;
-    for (const token of params.tokens) {
+    for (const token of params.parsers.markdownit.tokens) {
       if ((token.type === "blockquote_open") &&
           (prevToken.type === "blockquote_close")) {
         for (