markdownlint 0.33.0 → 0.35.0

package/lib/constants.js

@@ -8,7 +8,8 @@ module.exports.fixableRuleNames = [
   "MD012", "MD014", "MD018", "MD019", "MD020", "MD021",
   "MD022", "MD023", "MD026", "MD027", "MD030", "MD031",
   "MD032", "MD034", "MD037", "MD038", "MD039", "MD044",
-  "MD047", "MD049", "MD050", "MD051", "MD053", "MD054"
+  "MD047", "MD049", "MD050", "MD051", "MD053", "MD054",
+  "MD058"
 ];
 module.exports.homepage = "https://github.com/DavidAnson/markdownlint";
-module.exports.version = "0.33.0";
+module.exports.version = "0.35.0";

package/lib/markdownlint.d.ts

@@ -8,63 +8,8 @@ export = markdownlint;
  */
 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, LintContentCallback, LintCallback, Configuration, RuleConfiguration, ConfigurationParser, ReadConfigCallback, ResolveConfigExtendsCallback };
+    export { markdownlintSync as sync, readConfig, readConfigSync, getVersion, promises, GetMarkdownIt, RuleFunction, RuleParams, MarkdownParsers, ParserMarkdownIt, ParserMicromark, MarkdownItToken, MicromarkTokenType, MicromarkToken, RuleOnError, RuleOnErrorInfo, RuleOnErrorFixInfo, Rule, Options, Plugin, ToStringCallback, LintResults, LintError, FixInfo, LintContentCallback, LintCallback, Configuration, ConfigurationStrict, RuleConfiguration, ConfigurationParser, ReadConfigCallback, ResolveConfigExtendsCallback };
 }
-/**
- * Configuration options.
- */
-type Options = {
-    /**
-     * Configuration object.
-     */
-    config?: Configuration;
-    /**
-     * Configuration parsers.
-     */
-    configParsers?: ConfigurationParser[];
-    /**
-     * Custom rules.
-     */
-    customRules?: Rule[] | Rule;
-    /**
-     * Files to lint.
-     */
-    files?: string[] | string;
-    /**
-     * Front matter pattern.
-     */
-    frontMatter?: RegExp | null;
-    /**
-     * File system implementation.
-     */
-    fs?: any;
-    /**
-     * True to catch exceptions.
-     */
-    handleRuleFailures?: boolean;
-    /**
-     * Additional plugins.
-     */
-    markdownItPlugins?: Plugin[];
-    /**
-     * True to ignore HTML directives.
-     */
-    noInlineConfig?: boolean;
-    /**
-     * Results object version.
-     */
-    resultVersion?: number;
-    /**
-     * Strings to lint.
-     */
-    strings?: {
-        [x: string]: string;
-    };
-};
-/**
- * Called with the result of the lint function.
- */
-type LintCallback = (error: Error | null, results?: LintResults) => void;
 /**
  * Lint specified Markdown files synchronously.
  *
@@ -104,6 +49,10 @@ declare namespace promises {
     export { extendConfigPromise as extendConfig };
     export { readConfigPromise as readConfig };
 }
+/**
+ * Function to get an instance of the markdown-it parser.
+ */
+type GetMarkdownIt = () => any;
 /**
  * Function to implement rule logic.
  */
@@ -117,24 +66,55 @@ type RuleParams = {
      */
     name: string;
     /**
-     * Token objects from markdown-it.
+     * Markdown parser data.
      */
-    tokens: MarkdownItToken[];
+    parsers: MarkdownParsers;
     /**
      * File/string lines.
      */
-    lines: string[];
+    lines: readonly string[];
     /**
      * Front matter lines.
      */
-    frontMatterLines: string[];
+    frontMatterLines: readonly string[];
     /**
      * Rule configuration.
      */
     config: RuleConfiguration;
 };
 /**
- * Markdown-It token.
+ * Markdown parser data.
+ */
+type MarkdownParsers = {
+    /**
+     * Markdown parser data from markdown-it (only present when Rule.parser is "markdownit").
+     */
+    markdownit: ParserMarkdownIt;
+    /**
+     * Markdown parser data from micromark (only present when Rule.parser is "micromark").
+     */
+    micromark: ParserMicromark;
+};
+/**
+ * Markdown parser data from markdown-it.
+ */
+type ParserMarkdownIt = {
+    /**
+     * Token objects from markdown-it.
+     */
+    tokens: MarkdownItToken[];
+};
+/**
+ * Markdown parser data from micromark.
+ */
+type ParserMicromark = {
+    /**
+     * Token objects from micromark.
+     */
+    tokens: MicromarkToken[];
+};
+/**
+ * markdown-it token.
  */
 type MarkdownItToken = {
     /**
@@ -198,6 +178,44 @@ type MarkdownItToken = {
      */
     line: string;
 };
+type MicromarkTokenType = import("markdownlint-micromark").TokenType;
+/**
+ * micromark token.
+ */
+type MicromarkToken = {
+    /**
+     * Token type.
+     */
+    type: MicromarkTokenType;
+    /**
+     * Start line (1-based).
+     */
+    startLine: number;
+    /**
+     * Start column (1-based).
+     */
+    startColumn: number;
+    /**
+     * End line (1-based).
+     */
+    endLine: number;
+    /**
+     * End column (1-based).
+     */
+    endColumn: number;
+    /**
+     * Token text.
+     */
+    text: string;
+    /**
+     * Child tokens.
+     */
+    children: MicromarkToken[];
+    /**
+     * Parent token.
+     */
+    parent: MicromarkToken | null;
+};
 /**
  * Error-reporting callback.
  */
@@ -272,6 +290,10 @@ type Rule = {
      * Rule tag(s).
      */
     tags: string[];
+    /**
+     * Parser used.
+     */
+    parser: "markdownit" | "micromark" | "none";
     /**
      * True if asynchronous.
      */
@@ -281,6 +303,57 @@ type Rule = {
      */
     function: RuleFunction;
 };
+/**
+ * Configuration options.
+ */
+type Options = {
+    /**
+     * Configuration object.
+     */
+    config?: Configuration;
+    /**
+     * Configuration parsers.
+     */
+    configParsers?: ConfigurationParser[];
+    /**
+     * Custom rules.
+     */
+    customRules?: Rule[] | Rule;
+    /**
+     * Files to lint.
+     */
+    files?: string[] | string;
+    /**
+     * Front matter pattern.
+     */
+    frontMatter?: RegExp | null;
+    /**
+     * File system implementation.
+     */
+    fs?: any;
+    /**
+     * True to catch exceptions.
+     */
+    handleRuleFailures?: boolean;
+    /**
+     * Additional plugins.
+     */
+    markdownItPlugins?: Plugin[];
+    /**
+     * True to ignore HTML directives.
+     */
+    noInlineConfig?: boolean;
+    /**
+     * Results object version.
+     */
+    resultVersion?: number;
+    /**
+     * Strings to lint.
+     */
+    strings?: {
+        [x: string]: string;
+    };
+};
 /**
  * A markdown-it plugin.
  */
@@ -357,11 +430,20 @@ type FixInfo = {
  * Called with the result of linting a string or document.
  */
 type LintContentCallback = (error: Error | null, result?: LintError[]) => void;
+/**
+ * Called with the result of the lint function.
+ */
+type LintCallback = (error: Error | null, results?: LintResults) => void;
 /**
  * Configuration object for linting rules. For the JSON schema, see
  * {@link  ../schema/markdownlint-config-schema.json}.
  */
 type Configuration = import("./configuration").Configuration;
+/**
+ * Configuration object for linting rules strictly. For the JSON schema, see
+ * {@link  ../schema/markdownlint-config-schema-strict.json}.
+ */
+type ConfigurationStrict = import("./configuration-strict").ConfigurationStrict;
 /**
  * Rule configuration.
  */

package/lib/markdownlint.js

@@ -4,7 +4,6 @@
 
 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");
@@ -32,18 +31,17 @@ function validateRuleList(ruleList, synchronous) {
   const allIds = {};
   for (const [ index, rule ] of ruleList.entries()) {
     const customIndex = index - rules.length;
-    // eslint-disable-next-line no-inner-declarations, jsdoc/require-jsdoc
-    function newError(property) {
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    function newError(property, value) {
       return new Error(
-        "Property '" + property + "' of custom rule at index " +
-        customIndex + " is incorrect.");
+        `Property '${property}' of custom rule at index ${customIndex} is incorrect: '${value}'.`);
     }
     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);
+        result = newError(property, value);
       }
     }
     for (const propertyInfo of [
@@ -53,22 +51,31 @@ function validateRuleList(ruleList, synchronous) {
       const property = propertyInfo[0];
       const value = rule[property];
       if (!result && (!value || (typeof value !== propertyInfo[1]))) {
-        result = newError(property);
+        result = newError(property, value);
       }
     }
+    if (
+      !result &&
+      (rule.parser !== undefined) &&
+      (rule.parser !== "markdownit") &&
+      !((customIndex < 0) && (rule.parser === "micromark")) &&
+      (rule.parser !== "none")
+    ) {
+      result = newError("parser", rule.parser);
+    }
     if (
       !result &&
       rule.information &&
       !helpers.isUrl(rule.information)
     ) {
-      result = newError("information");
+      result = newError("information", rule.information);
     }
     if (
       !result &&
       (rule.asynchronous !== undefined) &&
       (typeof rule.asynchronous !== "boolean")
     ) {
-      result = newError("asynchronous");
+      result = newError("asynchronous", rule.asynchronous);
     }
     if (!result && rule.asynchronous && synchronous) {
       result = new Error(
@@ -218,13 +225,17 @@ function freezeToken(token) {
 /**
  * Annotate tokens with line/lineNumber and freeze them.
  *
- * @param {MarkdownItToken[]} tokens Array of markdown-it tokens.
+ * @param {import("markdown-it").Token[]} tokens Array of markdown-it tokens.
  * @param {string[]} lines Lines of Markdown content.
  * @returns {void}
  */
 function annotateAndFreezeTokens(tokens, lines) {
   let trMap = null;
-  for (const token of tokens) {
+  // eslint-disable-next-line jsdoc/valid-types
+  /** @type MarkdownItToken[] */
+  // @ts-ignore
+  const markdownItTokens = tokens;
+  for (const token of markdownItTokens) {
     // Provide missing maps for table content
     if (token.type === "tr_open") {
       trMap = token.map;
@@ -499,10 +510,18 @@ function getEnabledRulesPerLineNumber(
   handleInlineConfig(lines, enableDisableFile);
   handleInlineConfig(lines, captureRestoreEnableDisable, updateLineState);
   handleInlineConfig(lines, disableLineNextLine);
+  // Create the list of rules that are used at least once
+  const enabledRuleList = [];
+  for (const [ index, ruleName ] of allRuleNames.entries()) {
+    if (enabledRulesPerLineNumber.some((enabledRulesForLine) => enabledRulesForLine[ruleName])) {
+      enabledRuleList.push(ruleList[index]);
+    }
+  }
   // Return results
   return {
     effectiveConfig,
-    enabledRulesPerLineNumber
+    enabledRulesPerLineNumber,
+    enabledRuleList
   };
 }
 
@@ -514,7 +533,7 @@ function getEnabledRulesPerLineNumber(
  * names.
  * @param {string} name Identifier for the content.
  * @param {string} content Markdown content.
- * @param {Object} md Instance of markdown-it.
+ * @param {GetMarkdownIt} getMarkdownIt Getter for instance of markdown-it.
  * @param {Configuration} config Configuration object.
  * @param {ConfigurationParser[] | null} configParsers Configuration parsers.
  * @param {RegExp | null} frontMatter Regular expression for front matter.
@@ -529,7 +548,7 @@ function lintContent(
   aliasToRuleNames,
   name,
   content,
-  md,
+  getMarkdownIt,
   config,
   configParsers,
   frontMatter,
@@ -544,7 +563,7 @@ function lintContent(
   const { frontMatterLines } = removeFrontMatterResult;
   content = removeFrontMatterResult.content;
   // Get enabled rules per line (with HTML comments present)
-  const { effectiveConfig, enabledRulesPerLineNumber } =
+  const { effectiveConfig, enabledRulesPerLineNumber, enabledRuleList } =
     getEnabledRulesPerLineNumber(
       ruleList,
       content.split(helpers.newLineRe),
@@ -554,8 +573,11 @@ function lintContent(
       configParsers,
       aliasToRuleNames
     );
+  const needMarkdownItTokens = enabledRuleList.some(
+    (rule) => (rule.parser === "markdownit") || (rule.parser === undefined)
+  );
   // Parse content into parser tokens
-  const markdownitTokens = md.parse(content, {});
+  const markdownitTokens = needMarkdownItTokens ? getMarkdownIt().parse(content, {}) : [];
   const micromarkTokens = micromark.parse(content);
   // Hide the content of HTML comments from rules
   content = helpers.clearHtmlCommentText(content);
@@ -563,43 +585,56 @@ function lintContent(
   const lines = content.split(helpers.newLineRe);
   annotateAndFreezeTokens(markdownitTokens, lines);
   // Create (frozen) parameters for rules
-  const parsers = Object.freeze({
+  /** @type {MarkdownParsers} */
+  // @ts-ignore
+  const parsersMarkdownIt = Object.freeze({
     "markdownit": Object.freeze({
       "tokens": markdownitTokens
-    }),
+    })
+  });
+  /** @type {MarkdownParsers} */
+  // @ts-ignore
+  const parsersMicromark = Object.freeze({
     "micromark": Object.freeze({
       "tokens": micromarkTokens
     })
   });
+  /** @type {MarkdownParsers} */
+  // @ts-ignore
+  const parsersNone = Object.freeze({});
   const paramsBase = {
     name,
-    parsers,
-    "tokens": markdownitTokens,
     "lines": Object.freeze(lines),
     "frontMatterLines": Object.freeze(frontMatterLines)
   };
-  const lineMetadata =
-    helpers.getLineMetadata(paramsBase);
-  const codeBlockAndSpanRanges =
-    helpers.codeBlockAndSpanRanges(paramsBase, lineMetadata);
-  const flattenedLists =
-    helpers.flattenLists(paramsBase.parsers.markdownit.tokens);
-  const referenceLinkImageData =
-    helpers.getReferenceLinkImageData(paramsBase);
-  cache.set({
-    codeBlockAndSpanRanges,
-    flattenedLists,
-    lineMetadata,
-    referenceLinkImageData
+  cache.initialize({
+    ...paramsBase,
+    "parsers": parsersMicromark,
+    "config": null
   });
   // Function to run for each rule
   let results = [];
-  // eslint-disable-next-line jsdoc/require-jsdoc
-  function forRule(rule) {
+  /**
+   * @param {Rule} rule Rule.
+   * @returns {Promise<void> | null} Promise.
+   */
+  const forRule = (rule) => {
     // Configure rule
     const ruleName = rule.names[0].toUpperCase();
+    const tokens = {};
+    let parsers = parsersNone;
+    if (rule.parser === undefined) {
+      tokens.tokens = markdownitTokens;
+      parsers = parsersMarkdownIt;
+    } else if (rule.parser === "markdownit") {
+      parsers = parsersMarkdownIt;
+    } else if (rule.parser === "micromark") {
+      parsers = parsersMicromark;
+    }
     const params = {
       ...paramsBase,
+      ...tokens,
+      parsers,
       "config": effectiveConfig[ruleName]
     };
     // eslint-disable-next-line jsdoc/require-jsdoc
@@ -721,7 +756,7 @@ function lintContent(
       }
     }
     return null;
-  }
+  };
   // eslint-disable-next-line jsdoc/require-jsdoc
   function formatResults() {
     // Sort results by rule name by line number
@@ -769,8 +804,8 @@ function lintContent(
     return results;
   }
   // Run all rules
-  const ruleListAsync = ruleList.filter((rule) => rule.asynchronous);
-  const ruleListSync = ruleList.filter((rule) => !rule.asynchronous);
+  const ruleListAsync = enabledRuleList.filter((rule) => rule.asynchronous);
+  const ruleListSync = enabledRuleList.filter((rule) => !rule.asynchronous);
   const ruleListAsyncFirst = [
     ...ruleListAsync,
     ...ruleListSync
@@ -790,7 +825,7 @@ function lintContent(
   } catch (error) {
     callbackError(error);
   } finally {
-    cache.clear();
+    cache.initialize();
   }
 }
 
@@ -801,7 +836,7 @@ function lintContent(
  * @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 {GetMarkdownIt} getMarkdownIt Getter for instance of markdown-it.
  * @param {Configuration} config Configuration object.
  * @param {ConfigurationParser[] | null} configParsers Configuration parsers.
  * @param {RegExp | null} frontMatter Regular expression for front matter.
@@ -817,7 +852,7 @@ function lintFile(
   ruleList,
   aliasToRuleNames,
   file,
-  md,
+  getMarkdownIt,
   config,
   configParsers,
   frontMatter,
@@ -837,7 +872,7 @@ function lintFile(
       aliasToRuleNames,
       file,
       content,
-      md,
+      getMarkdownIt,
       config,
       configParsers,
       frontMatter,
@@ -875,6 +910,7 @@ function lintInput(options, synchronous, callback) {
         "description": rule.description,
         "information": helpers.cloneIfUrl(rule.information),
         "tags": helpers.cloneIfArray(rule.tags),
+        "parser": rule.parser,
         "asynchronous": rule.asynchronous,
         "function": rule.function
       }));
@@ -901,12 +937,16 @@ function lintInput(options, synchronous, callback) {
   const noInlineConfig = !!options.noInlineConfig;
   const resultVersion = (options.resultVersion === undefined) ?
     3 : options.resultVersion;
-  const md = markdownit({ "html": true });
-  const markdownItPlugins = options.markdownItPlugins || [];
-  for (const plugin of markdownItPlugins) {
-    // @ts-ignore
-    md.use(...plugin);
-  }
+  const getMarkdownIt = () => {
+    const markdownit = require("markdown-it");
+    const md = markdownit({ "html": true });
+    const markdownItPlugins = options.markdownItPlugins || [];
+    for (const plugin of markdownItPlugins) {
+      // @ts-ignore
+      md.use(...plugin);
+    }
+    return md;
+  };
   const fs = options.fs || require("node:fs");
   const aliasToRuleNames = mapAliasToRuleNames(ruleList);
   const results = newResults(ruleList);
@@ -938,7 +978,7 @@ function lintInput(options, synchronous, callback) {
         ruleList,
         aliasToRuleNames,
         currentItem,
-        md,
+        getMarkdownIt,
         config,
         configParsers,
         frontMatter,
@@ -957,7 +997,7 @@ function lintInput(options, synchronous, callback) {
         aliasToRuleNames,
         currentItem,
         strings[currentItem] || "",
-        md,
+        getMarkdownIt,
         config,
         configParsers,
         frontMatter,
@@ -1272,6 +1312,13 @@ module.exports = markdownlint;
 
 // Type declarations
 
+/**
+ * Function to get an instance of the markdown-it parser.
+ *
+ * @callback GetMarkdownIt
+ * @returns {import("markdown-it")}
+ */
+
 /**
  * Function to implement rule logic.
  *
@@ -1281,19 +1328,45 @@ module.exports = markdownlint;
  * @returns {void}
  */
 
+/* eslint-disable jsdoc/valid-types */
+
 /**
  * Rule parameters.
  *
  * @typedef {Object} RuleParams
  * @property {string} name File/string name.
- * @property {MarkdownItToken[]} tokens Token objects from markdown-it.
- * @property {string[]} lines File/string lines.
- * @property {string[]} frontMatterLines Front matter lines.
+ * @property {MarkdownParsers} parsers Markdown parser data.
+ * @property {readonly string[]} lines File/string lines.
+ * @property {readonly string[]} frontMatterLines Front matter lines.
  * @property {RuleConfiguration} config Rule configuration.
  */
 
+/* eslint-enable jsdoc/valid-types */
+
+/**
+ * Markdown parser data.
+ *
+ * @typedef {Object} MarkdownParsers
+ * @property {ParserMarkdownIt} markdownit Markdown parser data from markdown-it (only present when Rule.parser is "markdownit").
+ * @property {ParserMicromark} micromark Markdown parser data from micromark (only present when Rule.parser is "micromark").
+ */
+
+/**
+ * Markdown parser data from markdown-it.
+ *
+ * @typedef {Object} ParserMarkdownIt
+ * @property {MarkdownItToken[]} tokens Token objects from markdown-it.
+ */
+
 /**
- * Markdown-It token.
+ * Markdown parser data from micromark.
+ *
+ * @typedef {Object} ParserMicromark
+ * @property {MicromarkToken[]} tokens Token objects from micromark.
+ */
+
+/**
+ * markdown-it token.
  *
  * @typedef {Object} MarkdownItToken
  * @property {string[][]} attrs HTML attributes.
@@ -1313,6 +1386,22 @@ module.exports = markdownlint;
  * @property {string} line Line content.
  */
 
+/** @typedef {import("markdownlint-micromark").TokenType} MicromarkTokenType */
+
+/**
+ * micromark token.
+ *
+ * @typedef {Object} MicromarkToken
+ * @property {MicromarkTokenType} 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 {MicromarkToken[]} children Child tokens.
+ * @property {MicromarkToken | null} parent Parent token.
+ */
+
 /**
  * Error-reporting callback.
  *
@@ -1351,6 +1440,7 @@ module.exports = markdownlint;
  * @property {string} description Rule description.
  * @property {URL} [information] Link to more information.
  * @property {string[]} tags Rule tag(s).
+ * @property {"markdownit" | "micromark" | "none"} parser Parser used.
  * @property {boolean} [asynchronous] True if asynchronous.
  * @property {RuleFunction} function Rule implementation.
  */
@@ -1442,6 +1532,13 @@ module.exports = markdownlint;
  * @typedef {import("./configuration").Configuration} Configuration
  */
 
+/**
+ * Configuration object for linting rules strictly. For the JSON schema, see
+ * {@link ../schema/markdownlint-config-schema-strict.json}.
+ *
+ * @typedef {import("./configuration-strict").ConfigurationStrict} ConfigurationStrict
+ */
+
 /**
  * Rule configuration object.
  *