markdownlint 0.27.0 → 0.28.1

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.18.0",
+  "version": "0.19.0",
   "description": "A collection of markdownlint helper functions for custom rules",
   "main": "./helpers.js",
   "exports": "./helpers.js",
@@ -15,6 +15,9 @@
   "engines": {
     "node": ">=14.18.0"
   },
+  "dependencies": {
+    "markdownlint-micromark": "0.1.2"
+  },
   "keywords": [
     "markdownlint",
     "markdownlint-rule"

package/lib/constants.js

@@ -11,4 +11,4 @@ module.exports.fixableRuleNames = [
   "MD044", "MD047", "MD049", "MD050", "MD051", "MD053"
 ];
 module.exports.homepage = "https://github.com/DavidAnson/markdownlint";
-module.exports.version = "0.27.0";
+module.exports.version = "0.28.1";

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.
  *
@@ -101,6 +101,7 @@ declare function readConfigSync(file: string, parsers?: ConfigurationParser[], f
 declare function getVersion(): string;
 declare namespace promises {
     export { markdownlintPromise as markdownlint };
+    export { extendConfigPromise as extendConfig };
     export { readConfigPromise as readConfig };
 }
 /**
@@ -378,6 +379,16 @@ type ResolveConfigExtendsCallback = (err: Error | null, path?: string) => void;
  * @returns {Promise<LintResults>} Results object.
  */
 declare function markdownlintPromise(options: Options): Promise<LintResults>;
+/**
+ * Extend specified configuration object.
+ *
+ * @param {Configuration} config Configuration object.
+ * @param {string} file Configuration file name.
+ * @param {ConfigurationParser[]} [parsers] Parsing function(s).
+ * @param {Object} [fs] File system implementation.
+ * @returns {Promise<Configuration>} Configuration object.
+ */
+declare function extendConfigPromise(config: Configuration, file: string, parsers?: ConfigurationParser[], fs?: any): Promise<Configuration>;
 /**
  * Read specified configuration file.
  *

package/lib/markdownlint.js

@@ -4,7 +4,8 @@
 
 const path = require("node:path");
 const { promisify } = require("node:util");
-const markdownIt = require("markdown-it");
+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("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) {
@@ -1057,6 +1079,63 @@ function resolveConfigExtendsSync(configFile, referenceId, fs) {
   return resolvedExtendsFile;
 }
 
+/**
+ * Extend specified configuration object.
+ *
+ * @param {Configuration} config Configuration object.
+ * @param {string} file Configuration file name.
+ * @param {ConfigurationParser[]} parsers Parsing
+ * function(s).
+ * @param {Object} fs File system implementation.
+ * @param {ReadConfigCallback} callback Callback (err, result) function.
+ * @returns {void}
+ */
+function extendConfig(config, file, parsers, fs, callback) {
+  const configExtends = config.extends;
+  if (configExtends) {
+    return resolveConfigExtends(
+      file,
+      helpers.expandTildePath(configExtends, require("node:os")),
+      fs,
+      // eslint-disable-next-line no-use-before-define
+      (_, resolvedExtends) => readConfig(
+        // @ts-ignore
+        resolvedExtends,
+        parsers,
+        fs,
+        (err, extendsConfig) => {
+          if (err) {
+            return callback(err);
+          }
+          const result = {
+            ...extendsConfig,
+            ...config
+          };
+          delete result.extends;
+          return callback(null, result);
+        }
+      )
+    );
+  }
+  return callback(null, config);
+}
+
+const extendConfigPromisify = promisify && promisify(extendConfig);
+
+/**
+ * Extend specified configuration object.
+ *
+ * @param {Configuration} config Configuration object.
+ * @param {string} file Configuration file name.
+ * @param {ConfigurationParser[]} [parsers] Parsing function(s).
+ * @param {Object} [fs] File system implementation.
+ * @returns {Promise<Configuration>} Configuration object.
+ */
+function extendConfigPromise(config, file, parsers, fs) {
+  // @ts-ignore
+  return extendConfigPromisify(config, file, parsers, fs);
+}
+
 /**
  * Read specified configuration file.
  *
@@ -1083,8 +1162,7 @@ function readConfig(file, parsers, fs, callback) {
     fs = require("node:fs");
   }
   // Read file
-  const os = require("node:os");
-  file = helpers.expandTildePath(file, os);
+  file = helpers.expandTildePath(file, require("node:os"));
   fs.readFile(file, "utf8", (err, content) => {
     if (err) {
       // @ts-ignore
@@ -1098,34 +1176,8 @@ function readConfig(file, parsers, fs, callback) {
       return callback(new Error(message));
     }
     // Extend configuration
-    const configExtends = config.extends;
-    if (configExtends) {
-      delete config.extends;
-      return resolveConfigExtends(
-        file,
-        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
-            });
-          }
-        )
-      );
-    }
     // @ts-ignore
-    return callback(null, config);
+    return extendConfig(config, file, parsers, fs, callback);
   });
 }
 
@@ -1199,6 +1251,7 @@ markdownlint.readConfigSync = readConfigSync;
 markdownlint.getVersion = getVersion;
 markdownlint.promises = {
   "markdownlint": markdownlintPromise,
+  "extendConfig": extendConfigPromise,
   "readConfig": readConfigPromise
 };
 module.exports = markdownlint;
@@ -1295,7 +1348,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/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 (