markdownlint 0.29.0 → 0.31.0

package/helpers/micromark.cjs

@@ -4,9 +4,13 @@
 
 // @ts-ignore
 const {
-  gfmAutolinkLiteral, gfmFootnote, gfmTable, parse, postprocess, preprocess
+  gfmAutolinkLiteral, gfmFootnote, gfmTable, math, parse, postprocess,
+  preprocess
   // @ts-ignore
 } = require("markdownlint-micromark");
+const { newLineRe } = require("./shared.js");
+
+const flatTokensSymbol = Symbol("flat-tokens");
 
 /**
  * Markdown token.
@@ -21,25 +25,58 @@ const {
  * @property {Token[]} children Child tokens.
  */
 
+/**
+ * Returns whether a token is an htmlFlow type containing an HTML comment.
+ *
+ * @param {Token} token Micromark token.
+ * @returns {boolean} True iff token is htmlFlow containing a comment.
+ */
+function isHtmlFlowComment(token) {
+  const { text, type } = token;
+  if (
+    (type === "htmlFlow") &&
+    text.startsWith("<!--") &&
+    text.endsWith("-->")
+  ) {
+    const comment = text.slice(4, -3);
+    return (
+      !comment.startsWith(">") &&
+      !comment.startsWith("->") &&
+      !comment.endsWith("-") &&
+      !comment.includes("--")
+    );
+  }
+  return false;
+}
+
 /**
  * Parses a Markdown document and returns Micromark events.
  *
  * @param {string} markdown Markdown document.
- * @param {Object} [options] Options for micromark.
- * @param {boolean} [refsDefined] Whether to treat references as defined.
+ * @param {Object} [micromarkOptions] Options for micromark.
+ * @param {boolean} [referencesDefined] Treat references as defined.
  * @returns {Object[]} Micromark events.
  */
-function getMicromarkEvents(markdown, options = {}, refsDefined = true) {
+function getMicromarkEvents(
+  markdown,
+  micromarkOptions = {},
+  referencesDefined = true
+) {
 
   // Customize options object to add useful extensions
-  options.extensions = options.extensions || [];
-  options.extensions.push(gfmAutolinkLiteral, gfmFootnote(), gfmTable);
+  micromarkOptions.extensions = micromarkOptions.extensions || [];
+  micromarkOptions.extensions.push(
+    gfmAutolinkLiteral(),
+    gfmFootnote(),
+    gfmTable(),
+    math()
+  );
 
   // Use micromark to parse document into Events
   const encoding = undefined;
   const eol = true;
-  const parseContext = parse(options);
-  if (refsDefined) {
+  const parseContext = parse(micromarkOptions);
+  if (referencesDefined) {
     // Customize ParseContext to treat all references as defined
     parseContext.defined.includes = (searchElement) => searchElement.length > 0;
   }
@@ -52,93 +89,171 @@ function getMicromarkEvents(markdown, options = {}, refsDefined = true) {
  * Parses a Markdown document and returns (frozen) tokens.
  *
  * @param {string} markdown Markdown document.
- * @param {Object} [options] Options for micromark.
- * @param {boolean} [refsDefined] Whether to treat references as defined.
+ * @param {Object} micromarkOptions Options for micromark.
+ * @param {boolean} referencesDefined Treat references as defined.
+ * @param {number} lineDelta Offset to apply to start/end line.
  * @returns {Token[]} Micromark tokens (frozen).
  */
-function micromarkParse(markdown, options = {}, refsDefined = true) {
-
+function micromarkParseWithOffset(
+  markdown,
+  micromarkOptions,
+  referencesDefined,
+  lineDelta
+) {
   // Use micromark to parse document into Events
-  const events =
-    getMicromarkEvents(markdown, options, refsDefined);
+  const events = getMicromarkEvents(
+    markdown, micromarkOptions, referencesDefined
+  );
 
   // Create Token objects
   const document = [];
+  let flatTokens = [];
   let current = {
     "children": document
   };
   const history = [ current ];
+  let reparseOptions = null;
+  let lines = null;
+  let skipHtmlFlowChildren = false;
   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;
     const text = context.sliceSerialize(token);
-    if (kind === "enter") {
+    if ((kind === "enter") && !skipHtmlFlowChildren) {
       const previous = current;
       history.push(previous);
       current = {
         type,
-        startLine,
+        "startLine": startLine + lineDelta,
         startColumn,
-        endLine,
+        "endLine": endLine + lineDelta,
         endColumn,
         text,
         "children": []
       };
       previous.children.push(current);
-    } else if (kind === "exit") {
-      Object.freeze(current.children);
-      Object.freeze(current);
+      flatTokens.push(current);
       // @ts-ignore
-      current = history.pop();
+      if ((current.type === "htmlFlow") && !isHtmlFlowComment(current)) {
+        skipHtmlFlowChildren = true;
+        if (!reparseOptions || !lines) {
+          reparseOptions = {
+            ...micromarkOptions,
+            "extensions": [
+              {
+                "disable": {
+                  "null": [ "codeIndented", "htmlFlow" ]
+                }
+              }
+            ]
+          };
+          lines = markdown.split(newLineRe);
+        }
+        const reparseMarkdown = lines
+          .slice(current.startLine - 1, current.endLine)
+          .join("\n");
+        const tokens = micromarkParseWithOffset(
+          reparseMarkdown,
+          reparseOptions,
+          referencesDefined,
+          current.startLine - 1
+        );
+        current.children = tokens;
+        // Avoid stack overflow of Array.push(...spread)
+        // eslint-disable-next-line unicorn/prefer-spread
+        flatTokens = flatTokens.concat(tokens[flatTokensSymbol]);
+      }
+    } else if (kind === "exit") {
+      if (type === "htmlFlow") {
+        skipHtmlFlowChildren = false;
+      }
+      if (!skipHtmlFlowChildren) {
+        Object.freeze(current.children);
+        Object.freeze(current);
+        // @ts-ignore
+        current = history.pop();
+      }
     }
   }
 
   // Return document
+  Object.defineProperty(document, flatTokensSymbol, { "value": flatTokens });
   Object.freeze(document);
   return document;
 }
 
-// /**
-//  * Log the structure of a Micromark token list.
-//  *
-//  * @param {Token[]} tokens Micromark tokens.
-//  * @param {number} depth Tree depth.
-//  * @returns {void}
-//  */
-// function consoleLogTokens(tokens, depth = 0) {
-//   for (const token of tokens) {
-//     const { children, text, type } = token;
-//     console.log(
-//       `${" ".repeat(depth * 2)}${type} ${text.replace(/\n/g, "\\n")}`
-//     );
-//     if (children.length > 0) {
-//       consoleLogTokens(children, depth + 1);
-//     }
-//   }
-// }
+/**
+ * Parses a Markdown document and returns (frozen) tokens.
+ *
+ * @param {string} markdown Markdown document.
+ * @param {Object} [micromarkOptions] Options for micromark.
+ * @param {boolean} [referencesDefined] Treat references as defined.
+ * @returns {Token[]} Micromark tokens (frozen).
+ */
+function micromarkParse(
+  markdown,
+  micromarkOptions = {},
+  referencesDefined = true
+) {
+  return micromarkParseWithOffset(
+    markdown,
+    micromarkOptions,
+    referencesDefined,
+    0
+  );
+}
+
+/**
+ * @callback AllowedPredicate
+ * @param {Token} token Micromark token.
+ * @returns {boolean} True iff allowed.
+ */
+
+/**
+ * @callback TransformPredicate
+ * @param {Token} token Micromark token.
+ * @returns {Token[]} Child tokens.
+ */
 
 /**
  * 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.
+ * @param {AllowedPredicate} allowed Allowed token predicate.
+ * @param {TransformPredicate} [transformChildren] Transform 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);
+  const queue = [
+    {
+      "array": tokens,
+      "index": 0
     }
-    if (token.children.length > 0) {
-      const transformed =
-        transformChildren ? transformChildren(token) : token.children;
-      pending.unshift(...transformed);
+  ];
+  while (queue.length > 0) {
+    const current = queue[queue.length - 1];
+    const { array, index } = current;
+    if (index < array.length) {
+      const token = array[current.index++];
+      if (allowed(token)) {
+        result.push(token);
+      }
+      const { children } = token;
+      if (children.length > 0) {
+        const transformed =
+          transformChildren ? transformChildren(token) : children;
+        queue.push(
+          {
+            "array": transformed,
+            "index": 0
+          }
+        );
+      }
+    } else {
+      queue.pop();
     }
   }
   return result;
@@ -152,10 +267,33 @@ function filterByPredicate(tokens, allowed, transformChildren) {
  * @returns {Token[]} Filtered tokens.
  */
 function filterByTypes(tokens, allowed) {
-  return filterByPredicate(
-    tokens,
-    (token) => allowed.includes(token.type)
+  const predicate = (token) => allowed.includes(token.type);
+  const flatTokens = tokens[flatTokensSymbol];
+  if (flatTokens) {
+    return flatTokens.filter(predicate);
+  }
+  return filterByPredicate(tokens, predicate);
+}
+
+/**
+ * Gets the heading level of a Micromark heading tokan.
+ *
+ * @param {Token} heading Micromark heading token.
+ * @returns {number} Heading level.
+ */
+function getHeadingLevel(heading) {
+  const headingSequence = filterByTypes(
+    heading.children,
+    [ "atxHeadingSequence", "setextHeadingLineSequence" ]
   );
+  let level = 1;
+  const { text } = headingSequence[0];
+  if (text[0] === "#") {
+    level = Math.min(text.length, 6);
+  } else if (text[0] === "-") {
+    level = 2;
+  }
+  return level;
 }
 
 /**
@@ -232,6 +370,7 @@ module.exports = {
   "parse": micromarkParse,
   filterByPredicate,
   filterByTypes,
+  getHeadingLevel,
   getHtmlTagInfo,
   getMicromarkEvents,
   getTokenTextByType,

package/helpers/package.json

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

package/helpers/shared.js

@@ -0,0 +1,7 @@
+// @ts-check
+
+"use strict";
+
+// Regular expression for matching common newline characters
+// See NEWLINES_RE in markdown-it/lib/rules_core/normalize.js
+module.exports.newLineRe = /\r\n?|\n/g;

package/lib/cache.js

@@ -15,8 +15,6 @@ module.exports.codeBlockAndSpanRanges =
   () => map.get("codeBlockAndSpanRanges");
 module.exports.flattenedLists =
   () => map.get("flattenedLists");
-module.exports.htmlElementRanges =
-  () => map.get("htmlElementRanges");
 module.exports.lineMetadata =
   () => map.get("lineMetadata");
 module.exports.referenceLinkImageData =

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.29.0";
+module.exports.version = "0.31.0";

package/lib/markdownlint.d.ts

@@ -8,7 +8,7 @@ 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, LintCallback, Configuration, RuleConfiguration, ConfigurationParser, ReadConfigCallback, ResolveConfigExtendsCallback };
+    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 };
 }
 /**
  * Configuration options.
@@ -64,7 +64,7 @@ type Options = {
 /**
  * Called with the result of the lint function.
  */
-type LintCallback = (err: Error | null, results?: LintResults) => void;
+type LintCallback = (error: Error | null, results?: LintResults) => void;
 /**
  * Lint specified Markdown files synchronously.
  *
@@ -218,6 +218,10 @@ type RuleOnErrorInfo = {
      * Context for the error.
      */
     context?: string;
+    /**
+     * Link to more information.
+     */
+    information?: URL;
     /**
      * Column number (1-based) and length.
      */
@@ -349,6 +353,10 @@ type FixInfo = {
      */
     insertText?: string;
 };
+/**
+ * Called with the result of linting a string or document.
+ */
+type LintContentCallback = (error: Error | null, result?: LintError[]) => void;
 /**
  * Configuration object for linting rules. For a detailed schema, see
  * {@link  ../schema/markdownlint-config-schema.json}.

package/lib/markdownlint.js

@@ -59,7 +59,7 @@ function validateRuleList(ruleList, synchronous) {
     if (
       !result &&
       rule.information &&
-      (Object.getPrototypeOf(rule.information) !== URL.prototype)
+      !helpers.isUrl(rule.information)
     ) {
       result = newError("information");
     }
@@ -481,7 +481,7 @@ function getEnabledRulesPerLineNumber(
         applyEnableDisable(
           action,
           parameter,
-          enabledRulesPerLineNumber[nextLineNumber] || {}
+          enabledRulesPerLineNumber[nextLineNumber]
         );
     }
   }
@@ -520,7 +520,7 @@ function getEnabledRulesPerLineNumber(
  * @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.
- * @param {Function} callback Callback (err, result) function.
+ * @param {LintContentCallback} callback Callback (err, result) function.
  * @returns {void}
  */
 function lintContent(
@@ -583,14 +583,11 @@ function lintContent(
     helpers.codeBlockAndSpanRanges(paramsBase, lineMetadata);
   const flattenedLists =
     helpers.flattenLists(paramsBase.parsers.markdownit.tokens);
-  const htmlElementRanges =
-    helpers.htmlElementRanges(paramsBase, lineMetadata);
   const referenceLinkImageData =
     helpers.getReferenceLinkImageData(paramsBase);
   cache.set({
     codeBlockAndSpanRanges,
     flattenedLists,
-    htmlElementRanges,
     lineMetadata,
     referenceLinkImageData
   });
@@ -629,6 +626,10 @@ function lintContent(
         !helpers.isString(errorInfo.context)) {
         throwError("context");
       }
+      if (errorInfo.information &&
+        !helpers.isUrl(errorInfo.information)) {
+        throwError("information");
+      }
       if (errorInfo.range &&
         (!Array.isArray(errorInfo.range) ||
           (errorInfo.range.length !== 2) ||
@@ -681,12 +682,13 @@ function lintContent(
           cleanFixInfo.insertText = fixInfo.insertText;
         }
       }
+      const information = errorInfo.information || rule.information;
       results.push({
         lineNumber,
         "ruleName": rule.names[0],
         "ruleNames": rule.names,
         "ruleDescription": rule.description,
-        "ruleInformation": rule.information ? rule.information.href : null,
+        "ruleInformation": information ? information.href : null,
         "errorDetail": errorInfo.detail || null,
         "errorContext": errorInfo.context || null,
         "errorRange": errorInfo.range ? [ ...errorInfo.range ] : null,
@@ -807,7 +809,7 @@ function lintContent(
  * @param {number} resultVersion Version of the LintResults object to return.
  * @param {Object} fs File system implementation.
  * @param {boolean} synchronous Whether to execute synchronously.
- * @param {Function} callback Callback (err, result) function.
+ * @param {LintContentCallback} callback Callback (err, result) function.
  * @returns {void}
  */
 function lintFile(
@@ -857,15 +859,26 @@ function lintFile(
  *
  * @param {Options | null} options Options object.
  * @param {boolean} synchronous Whether to execute synchronously.
- * @param {Function} callback Callback (err, result) function.
+ * @param {LintCallback} callback Callback (err, result) function.
  * @returns {void}
  */
 function lintInput(options, synchronous, callback) {
   // Normalize inputs
   options = options || {};
   callback = callback || function noop() {};
+  const customRuleList =
+    [ options.customRules || [] ]
+      .flat()
+      .map((rule) => ({
+        "names": helpers.cloneIfArray(rule.names),
+        "description": rule.description,
+        "information": helpers.cloneIfUrl(rule.information),
+        "tags": helpers.cloneIfArray(rule.tags),
+        "asynchronous": rule.asynchronous,
+        "function": rule.function
+      }));
   // eslint-disable-next-line unicorn/prefer-spread
-  const ruleList = rules.concat(options.customRules || []);
+  const ruleList = rules.concat(customRuleList);
   const ruleErr = validateRuleList(ruleList, synchronous);
   if (ruleErr) {
     callback(ruleErr);
@@ -1009,7 +1022,7 @@ function markdownlintPromise(options) {
  * @returns {LintResults} Results object.
  */
 function markdownlintSync(options) {
-  let results = {};
+  let results = null;
   lintInput(options, true, function callback(error, res) {
     if (error) {
       throw error;
@@ -1163,6 +1176,7 @@ function readConfig(file, parsers, fs, callback) {
   }
   // Read file
   file = helpers.expandTildePath(file, require("node:os"));
+  // eslint-disable-next-line n/prefer-promises/fs
   fs.readFile(file, "utf8", (err, content) => {
     if (err) {
       // @ts-ignore
@@ -1314,6 +1328,7 @@ module.exports = markdownlint;
  * @property {number} lineNumber Line number (1-based).
  * @property {string} [detail] Detail about the error.
  * @property {string} [context] Context for the error.
+ * @property {URL} [information] Link to more information.
  * @property {number[]} [range] Column number (1-based) and length.
  * @property {RuleOnErrorFixInfo} [fixInfo] Fix information.
  */
@@ -1402,12 +1417,21 @@ module.exports = markdownlint;
  * @property {string} [insertText] Text to insert (after deleting).
  */
 
+/**
+ * Called with the result of linting a string or document.
+ *
+ * @callback LintContentCallback
+ * @param {Error | null} error Error iff failed.
+ * @param {LintError[]} [result] Result iff successful.
+ * @returns {void}
+ */
+
 /**
  * Called with the result of the lint function.
  *
  * @callback LintCallback
- * @param {Error | null} err Error object or null.
- * @param {LintResults} [results] Lint results.
+ * @param {Error | null} error Error object iff failed.
+ * @param {LintResults} [results] Lint results iff succeeded.
  * @returns {void}
  */