markdownlint 0.28.2 → 0.30.0

package/helpers/micromark.cjs

@@ -4,9 +4,11 @@
 
 // @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");
 
 /**
  * Markdown token.
@@ -19,27 +21,40 @@ const {
  * @property {number} endColumn End column (1-based).
  * @property {string} text Token text.
  * @property {Token[]} children Child tokens.
+ * @property {Token[]} [htmlFlowChildren] Child tokens for htmlFlow.
  */
 
 /**
  * Parses a Markdown document and returns Micromark events.
  *
  * @param {string} markdown Markdown document.
- * @param {Object} [options] Options for micromark.
+ * @param {Object} [micromarkOptions] Options for micromark.
+ * @param {boolean} [referencesDefined] Treat references as defined.
  * @returns {Object[]} Micromark events.
  */
-function getMicromarkEvents(markdown, options = {}) {
+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);
-  // Customize ParseContext to treat all references as defined
-  parseContext.defined.includes = (searchElement) => searchElement.length > 0;
+  const parseContext = parse(micromarkOptions);
+  if (referencesDefined) {
+    // 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;
@@ -49,13 +64,21 @@ function getMicromarkEvents(markdown, options = {}) {
  * Parses a Markdown document and returns (frozen) tokens.
  *
  * @param {string} markdown Markdown document.
- * @param {Object} [options] Options for micromark.
+ * @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 = {}) {
-
+function micromarkParseWithOffset(
+  markdown,
+  micromarkOptions,
+  referencesDefined,
+  lineDelta
+) {
   // Use micromark to parse document into Events
-  const events = getMicromarkEvents(markdown, options);
+  const events = getMicromarkEvents(
+    markdown, micromarkOptions, referencesDefined
+  );
 
   // Create Token objects
   const document = [];
@@ -63,29 +86,50 @@ function micromarkParse(markdown, options = {}) {
     "children": document
   };
   const history = [ current ];
+  let reparseOptions = null;
+  let lines = null;
   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
-    }
+    const text = context.sliceSerialize(token);
     if (kind === "enter") {
       const previous = current;
       history.push(previous);
       current = {
         type,
-        startLine,
+        "startLine": startLine + lineDelta,
         startColumn,
-        endLine,
+        "endLine": endLine + lineDelta,
         endColumn,
         text,
         "children": []
       };
+      if (current.type === "htmlFlow") {
+        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");
+        current.htmlFlowChildren = micromarkParseWithOffset(
+          reparseMarkdown,
+          reparseOptions,
+          referencesDefined,
+          current.startLine - 1
+        );
+      }
       previous.children.push(current);
     } else if (kind === "exit") {
       Object.freeze(current.children);
@@ -100,6 +144,27 @@ function micromarkParse(markdown, options = {}) {
   return document;
 }
 
+/**
+ * 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
+  );
+}
+
 /**
  * Filter a list of Micromark tokens by predicate.
  *
@@ -139,6 +204,68 @@ function filterByTypes(tokens, allowed) {
   );
 }
 
+/**
+ * Filter a list of Micromark tokens for HTML tokens.
+ *
+ * @param {Token[]} tokens Micromark tokens.
+ * @returns {Token[]} Filtered tokens.
+ */
+function filterByHtmlTokens(tokens) {
+  const result = [];
+  const pending = [ tokens ];
+  let current = null;
+  while ((current = pending.shift())) {
+    for (const token of filterByTypes(current, [ "htmlFlow", "htmlText" ])) {
+      if (token.type === "htmlText") {
+        result.push(token);
+      } else {
+        // token.type === "htmlFlow"
+        // @ts-ignore
+        pending.push(token.htmlFlowChildren);
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Returns a list of all nested child tokens.
+ *
+ * @param {Token} parent Micromark token.
+ * @returns {Token[]} Flattened children.
+ */
+function flattenedChildren(parent) {
+  const result = [];
+  const pending = [ ...parent.children ];
+  let token = null;
+  while ((token = pending.shift())) {
+    result.push(token);
+    pending.unshift(...token.children);
+  }
+  return result;
+}
+
+/**
+ * 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;
+}
+
 /**
  * Gets information about the tag in an HTML token.
  *
@@ -198,12 +325,27 @@ function matchAndGetTokensByType(tokens, matchTypes, resultTypes) {
   return result;
 }
 
+/**
+ * Returns the specified token iff it is of the desired type.
+ *
+ * @param {Token} token Micromark token candidate.
+ * @param {string} type Desired type.
+ * @returns {Token | null} Token instance.
+ */
+function tokenIfType(token, type) {
+  return (token && (token.type === type)) ? token : null;
+}
+
 module.exports = {
   "parse": micromarkParse,
+  filterByHtmlTokens,
   filterByPredicate,
   filterByTypes,
+  flattenedChildren,
+  getHeadingLevel,
   getHtmlTagInfo,
   getMicromarkEvents,
   getTokenTextByType,
-  matchAndGetTokensByType
+  matchAndGetTokensByType,
+  tokenIfType
 };

package/helpers/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markdownlint-rule-helpers",
-  "version": "0.19.0",
+  "version": "0.21.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.28.2";
+module.exports.version = "0.30.0";

package/lib/markdownlint.d.ts

@@ -218,6 +218,10 @@ type RuleOnErrorInfo = {
      * Context for the error.
      */
     context?: string;
+    /**
+     * Link to more information.
+     */
+    information?: URL;
     /**
      * Column number (1-based) and length.
      */

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]
         );
     }
   }
@@ -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,
@@ -864,8 +866,19 @@ 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);
@@ -1314,6 +1327,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.
  */

package/lib/md022.js

@@ -2,8 +2,25 @@
 
 "use strict";
 
-const { addErrorDetailIf, blockquotePrefixRe, filterTokens, isBlankLine } =
+const { addErrorDetailIf, blockquotePrefixRe, isBlankLine } =
   require("../helpers");
+const { filterByTypes, getHeadingLevel } =
+  require("../helpers/micromark.cjs");
+
+const defaultLines = 1;
+
+const getLinesFunction = (linesParam) => {
+  if (Array.isArray(linesParam)) {
+    const linesArray = new Array(6).fill(defaultLines);
+    for (const [ index, value ] of [ ...linesParam.entries() ].slice(0, 6)) {
+      linesArray[index] = value;
+    }
+    return (heading) => linesArray[getHeadingLevel(heading) - 1];
+  }
+  // Coerce linesParam to a number
+  const lines = (linesParam === undefined) ? defaultLines : Number(linesParam);
+  return () => lines;
+};
 
 const getBlockQuote = (str, count) => (
   (str || "")
@@ -19,50 +36,73 @@ module.exports = {
   "description": "Headings should be surrounded by blank lines",
   "tags": [ "headings", "headers", "blank_lines" ],
   "function": function MD022(params, onError) {
-    let linesAbove = params.config.lines_above;
-    linesAbove = Number((linesAbove === undefined) ? 1 : linesAbove);
-    let linesBelow = params.config.lines_below;
-    linesBelow = Number((linesBelow === undefined) ? 1 : linesBelow);
-    const { lines } = params;
-    filterTokens(params, "heading_open", (token) => {
-      const [ topIndex, nextIndex ] = token.map;
-      let actualAbove = 0;
-      for (let i = 0; i < linesAbove; i++) {
-        if (isBlankLine(lines[topIndex - i - 1])) {
+    const getLinesAbove = getLinesFunction(params.config.lines_above);
+    const getLinesBelow = getLinesFunction(params.config.lines_below);
+    const { lines, parsers } = params;
+    const headings = filterByTypes(
+      parsers.micromark.tokens,
+      [ "atxHeading", "setextHeading" ]
+    );
+    for (const heading of headings) {
+      const { startLine, endLine } = heading;
+      const line = lines[startLine - 1].trim();
+
+      // Check lines above
+      const linesAbove = getLinesAbove(heading);
+      if (linesAbove >= 0) {
+        let actualAbove = 0;
+        for (
+          let i = 0;
+          (i < linesAbove) && isBlankLine(lines[startLine - 2 - i]);
+          i++
+        ) {
           actualAbove++;
         }
+        addErrorDetailIf(
+          onError,
+          startLine,
+          linesAbove,
+          actualAbove,
+          "Above",
+          line,
+          null,
+          {
+            "insertText": getBlockQuote(
+              lines[startLine - 2],
+              linesAbove - actualAbove
+            )
+          }
+        );
       }
-      addErrorDetailIf(
-        onError,
-        topIndex + 1,
-        linesAbove,
-        actualAbove,
-        "Above",
-        lines[topIndex].trim(),
-        null,
-        {
-          "insertText":
-            getBlockQuote(lines[topIndex - 1], linesAbove - actualAbove)
-        });
-      let actualBelow = 0;
-      for (let i = 0; i < linesBelow; i++) {
-        if (isBlankLine(lines[nextIndex + i])) {
+
+      // Check lines below
+      const linesBelow = getLinesBelow(heading);
+      if (linesBelow >= 0) {
+        let actualBelow = 0;
+        for (
+          let i = 0;
+          (i < linesBelow) && isBlankLine(lines[endLine + i]);
+          i++
+        ) {
           actualBelow++;
         }
+        addErrorDetailIf(
+          onError,
+          startLine,
+          linesBelow,
+          actualBelow,
+          "Below",
+          line,
+          null,
+          {
+            "lineNumber": endLine + 1,
+            "insertText": getBlockQuote(
+              lines[endLine],
+              linesBelow - actualBelow
+            )
+          }
+        );
       }
-      addErrorDetailIf(
-        onError,
-        topIndex + 1,
-        linesBelow,
-        actualBelow,
-        "Below",
-        lines[topIndex].trim(),
-        null,
-        {
-          "lineNumber": nextIndex + 1,
-          "insertText":
-            getBlockQuote(lines[nextIndex], linesBelow - actualBelow)
-        });
-    });
+    }
   }
 };

package/lib/md026.js

@@ -2,10 +2,10 @@
 
 "use strict";
 
-const { addError, allPunctuationNoQuestion, escapeForRegExp, forEachHeading } =
-  require("../helpers");
+const { addError, allPunctuationNoQuestion, endOfLineGemojiCodeRe,
+  endOfLineHtmlEntityRe, escapeForRegExp } = require("../helpers");
+const { filterByTypes } = require("../helpers/micromark.cjs");
 
-const endOfLineHtmlEntityRe = /&#?[\da-zA-Z]+;$/;
 
 module.exports = {
   "names": [ "MD026", "no-trailing-punctuation" ],
@@ -18,19 +18,26 @@ module.exports = {
     );
     const trailingPunctuationRe =
       new RegExp("\\s*[" + escapeForRegExp(punctuation) + "]+$");
-    forEachHeading(params, (heading) => {
-      const { line, lineNumber } = heading;
-      const trimmedLine = line.replace(/([^\s#])[\s#]+$/, "$1");
-      const match = trailingPunctuationRe.exec(trimmedLine);
-      if (match && !endOfLineHtmlEntityRe.test(trimmedLine)) {
+    const headings = filterByTypes(
+      params.parsers.micromark.tokens,
+      [ "atxHeadingText", "setextHeadingText" ]
+    );
+    for (const heading of headings) {
+      const { endLine, startColumn, text } = heading;
+      const match = trailingPunctuationRe.exec(text);
+      if (
+        match &&
+        !endOfLineHtmlEntityRe.test(text) &&
+        !endOfLineGemojiCodeRe.test(text)
+      ) {
         const fullMatch = match[0];
-        const column = match.index + 1;
+        const column = startColumn + match.index;
         const length = fullMatch.length;
         addError(
           onError,
-          lineNumber,
+          endLine,
           `Punctuation: '${fullMatch}'`,
-          null,
+          undefined,
           [ column, length ],
           {
             "editColumn": column,
@@ -38,6 +45,6 @@ module.exports = {
           }
         );
       }
-    });
+    }
   }
 };