Introduce options.markdownItFactory (and remove options.markdownItPlugins) so the markdown-it parser can be removed as a direct dependency because it is no longer used by default.

2025-12-16 14:00:13 +01:00 · 2024-12-25 20:42:32 -08:00 · 2024-12-25 20:42:32 -08:00 · d4b981bcb3
commit d4b981bcb3
parent 3cbe1cb6c5
11 changed files with 172 additions and 67 deletions
--- a/lib/exports.d.mts
+++ b/lib/exports.d.mts
@ -7,6 +7,7 @@ export type LintCallback = import("./markdownlint.mjs").LintCallback;
 export type LintContentCallback = import("./markdownlint.mjs").LintContentCallback;
 export type LintError = import("./markdownlint.mjs").LintError;
 export type LintResults = import("./markdownlint.mjs").LintResults;
+export type MarkdownItFactory = import("./markdownlint.mjs").MarkdownItFactory;
 export type MarkdownItToken = import("./markdownlint.mjs").MarkdownItToken;
 export type MarkdownParsers = import("./markdownlint.mjs").MarkdownParsers;
 export type MicromarkToken = import("./markdownlint.mjs").MicromarkToken;
--- a/lib/exports.mjs
+++ b/lib/exports.mjs
@ -11,6 +11,7 @@ export { resolveModule } from "./resolve-module.cjs";
 /** @typedef {import("./markdownlint.mjs").LintContentCallback} LintContentCallback */
 /** @typedef {import("./markdownlint.mjs").LintError} LintError */
 /** @typedef {import("./markdownlint.mjs").LintResults} LintResults */
+/** @typedef {import("./markdownlint.mjs").MarkdownItFactory} MarkdownItFactory */
 /** @typedef {import("./markdownlint.mjs").MarkdownItToken} MarkdownItToken */
 /** @typedef {import("./markdownlint.mjs").MarkdownParsers} MarkdownParsers */
 /** @typedef {import("./markdownlint.mjs").MicromarkToken} MicromarkToken */
--- a/lib/markdownit.cjs
+++ b/lib/markdownit.cjs
@ -4,6 +4,8 @@

 const { newLineRe } = require("../helpers");

+// @ts-expect-error https://github.com/microsoft/TypeScript/issues/52529
+/** @typedef {import("markdownlint").MarkdownItFactory} MarkdownItFactory */
 // @ts-expect-error https://github.com/microsoft/TypeScript/issues/52529
 /** @typedef {import("markdownlint").MarkdownItToken} MarkdownItToken */
 // @ts-expect-error https://github.com/microsoft/TypeScript/issues/52529
@ -97,7 +99,7 @@ function freezeToken(token) {
 /**
 * Annotate tokens with line/lineNumber and freeze them.
 *
- * @param {Object[]} 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}
 */
@ -152,21 +154,15 @@ function annotateAndFreezeTokens(tokens, lines) {
 /**
 * Gets an array of markdown-it tokens for the input.
 *
- * @param {Plugin[]} markdownItPlugins Additional plugins.
+ * @param {MarkdownItFactory} markdownItFactory Function to create a markdown-it parser.
 * @param {string} content Markdown content.
 * @param {string[]} lines Lines of Markdown content.
- * @returns {MarkdownItToken} Array of markdown-it tokens.
+ * @returns {MarkdownItToken[]} Array of markdown-it tokens.
 */
-function getMarkdownItTokens(markdownItPlugins, content, lines) {
-  const markdownit = require("markdown-it");
-  const md = markdownit({ "html": true });
-  for (const plugin of markdownItPlugins) {
-    // @ts-ignore
-    md.use(...plugin);
-  }
-  const tokens = md.parse(content, {});
+function getMarkdownItTokens(markdownItFactory, content, lines) {
+  const markdownIt = markdownItFactory();
+  const tokens = markdownIt.parse(content, {});
  annotateAndFreezeTokens(tokens, lines);
-  // @ts-ignore
  return tokens;
 };

--- a/lib/markdownlint.d.mts
+++ b/lib/markdownlint.d.mts
@ -357,6 +357,23 @@ export type Rule = {
     */
    function: RuleFunction;
 };
+/**
+ * Method used by the markdown-it parser to parse input.
+ */
+export type MarkdownItParse = (src: string, env: any) => any[];
+/**
+ * Instance of the markdown-it parser.
+ */
+export type MarkdownIt = {
+    /**
+     * Method to parse input.
+     */
+    parse: MarkdownItParse;
+};
+/**
+ * Gets an instance of the markdown-it parser. Any plugins should already have been loaded.
+ */
+export type MarkdownItFactory = () => MarkdownIt;
 /**
 * Configuration options.
 */
@ -390,9 +407,9 @@ export type Options = {
     */
    handleRuleFailures?: boolean;
    /**
-     * Additional plugins.
+     * Function to create a markdown-it parser.
     */
-    markdownItPlugins?: Plugin[];
+    markdownItFactory?: MarkdownItFactory;
    /**
     * True to ignore HTML directives.
     */
--- a/lib/markdownlint.mjs
+++ b/lib/markdownlint.mjs
@ -447,7 +447,7 @@ function getEnabledRulesPerLineNumber(
 * names.
 * @param {string} name Identifier for the content.
 * @param {string} content Markdown content.
- * @param {Plugin[]} markdownItPlugins Additional plugins.
+ * @param {MarkdownItFactory} markdownItFactory Function to create a markdown-it parser.
 * @param {Configuration} config Configuration object.
 * @param {ConfigurationParser[] | null} configParsers Configuration parsers.
 * @param {RegExp | null} frontMatter Regular expression for front matter.
@ -462,7 +462,7 @@ function lintContent(
  aliasToRuleNames,
  name,
  content,
-  markdownItPlugins,
+  markdownItFactory,
  config,
  configParsers,
  frontMatter,
@ -502,7 +502,7 @@ function lintContent(
  // Parse content into lines and get markdown-it tokens
  const lines = content.split(helpers.newLineRe);
  const markdownitTokens = needMarkdownItTokens ?
-    requireMarkdownItCjs().getMarkdownItTokens(markdownItPlugins, preClearedContent, lines) :
+    requireMarkdownItCjs().getMarkdownItTokens(markdownItFactory, preClearedContent, lines) :
    [];
  // Create (frozen) parameters for rules
  /** @type {MarkdownParsers} */
@ -754,10 +754,9 @@ 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 {Object.<string, string[]>} aliasToRuleNames Map of alias to rule names.
 * @param {string} file Path of file to lint.
- * @param {Plugin[]} markdownItPlugins Additional plugins.
+ * @param {MarkdownItFactory} markdownItFactory Function to create a markdown-it parser.
 * @param {Configuration} config Configuration object.
 * @param {ConfigurationParser[] | null} configParsers Configuration parsers.
 * @param {RegExp | null} frontMatter Regular expression for front matter.
@ -773,7 +772,7 @@ function lintFile(
  ruleList,
  aliasToRuleNames,
  file,
-  markdownItPlugins,
+  markdownItFactory,
  config,
  configParsers,
  frontMatter,
@ -793,7 +792,7 @@ function lintFile(
      aliasToRuleNames,
      file,
      content,
-      markdownItPlugins,
+      markdownItFactory,
      config,
      configParsers,
      frontMatter,
@ -860,7 +859,9 @@ function lintInput(options, synchronous, callback) {
  const resultVersion = (options.resultVersion === undefined) ?
    3 :
    options.resultVersion;
-  const markdownItPlugins = options.markdownItPlugins || [];
+  const markdownItFactory =
+    options.markdownItFactory ||
+    (() => { throw new Error("The option 'markdownItFactory' was required (due to the option 'customRules' including a rule requiring the 'markdown-it' parser), but 'markdownItFactory' was not set."); });
  const fs = options.fs || nodeFs;
  const aliasToRuleNames = mapAliasToRuleNames(ruleList);
  const results = newResults(ruleList);
@ -892,7 +893,7 @@ function lintInput(options, synchronous, callback) {
        ruleList,
        aliasToRuleNames,
        currentItem,
-        markdownItPlugins,
+        markdownItFactory,
        config,
        configParsers,
        frontMatter,
@ -911,7 +912,7 @@ function lintInput(options, synchronous, callback) {
        aliasToRuleNames,
        currentItem,
        strings[currentItem] || "",
-        markdownItPlugins,
+        markdownItFactory,
        config,
        configParsers,
        frontMatter,
@ -1473,6 +1474,29 @@ export function getVersion() {
 * @property {RuleFunction} function Rule implementation.
 */

+/**
+ * Method used by the markdown-it parser to parse input.
+ *
+ * @callback MarkdownItParse
+ * @param {string} src Source string.
+ * @param {Object} env Environment sandbox.
+ * @returns {import("markdown-it").Token[]} Tokens.
+ */
+
+/**
+ * Instance of the markdown-it parser.
+ *
+ * @typedef MarkdownIt
+ * @property {MarkdownItParse} parse Method to parse input.
+ */
+
+/**
+ * Gets an instance of the markdown-it parser. Any plugins should already have been loaded.
+ *
+ * @callback MarkdownItFactory
+ * @returns {MarkdownIt} Instance of the markdown-it parser.
+ */
+
 /**
 * Configuration options.
 *
@ -1484,7 +1508,7 @@ export function getVersion() {
 * @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.
+ * @property {MarkdownItFactory} [markdownItFactory] Function to create a markdown-it parser.
 * @property {boolean} [noInlineConfig] True to ignore HTML directives.
 * @property {number} [resultVersion] Results object version.
 * @property {Object.<string, string>} [strings] Strings to lint.
@ -1501,7 +1525,7 @@ export function getVersion() {
 *
 * @callback ToStringCallback
 * @param {boolean} [ruleAliases] True to use rule aliases.
- * @returns {string}
+ * @returns {string} Pretty-printed results.
 */

 /**