markdownlint 0.35.0 → 0.36.1

package/helpers/micromark-helpers.cjs

@@ -0,0 +1,296 @@
+// @ts-check
+
+"use strict";
+
+const { flatTokensSymbol, htmlFlowSymbol } = require("./shared.js");
+
+/** @typedef {import("markdownlint-micromark").TokenType} TokenType */
+/** @typedef {import("../lib/markdownlint.js").MicromarkToken} Token */
+
+/**
+ * Determines if a Micromark token is within an htmlFlow type.
+ *
+ * @param {Token} token Micromark token.
+ * @returns {boolean} True iff the token is within an htmlFlow type.
+ */
+function inHtmlFlow(token) {
+  return Boolean(token[htmlFlowSymbol]);
+}
+
+/**
+ * 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("-")
+      // The following condition from the CommonMark specification is commented
+      // to avoid parsing HTML comments that include "--" because that is NOT a
+      // condition of the HTML specification.
+      // https://spec.commonmark.org/0.30/#raw-html
+      // https://html.spec.whatwg.org/multipage/syntax.html#comments
+      // && !comment.includes("--")
+    );
+  }
+  return false;
+}
+
+/**
+ * Adds a range of numbers to a set.
+ *
+ * @param {Set<number>} set Set of numbers.
+ * @param {number} start Starting number.
+ * @param {number} end Ending number.
+ * @returns {void}
+ */
+function addRangeToSet(set, start, end) {
+  for (let i = start; i <= end; i++) {
+    set.add(i);
+  }
+}
+
+/**
+ * @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 {AllowedPredicate} [allowed] Allowed token predicate.
+ * @param {TransformPredicate} [transformChildren] Transform predicate.
+ * @returns {Token[]} Filtered tokens.
+ */
+function filterByPredicate(tokens, allowed, transformChildren) {
+  allowed = allowed || (() => true);
+  const result = [];
+  const queue = [
+    {
+      "array": tokens,
+      "index": 0
+    }
+  ];
+  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;
+}
+
+/**
+ * Filter a list of Micromark tokens by type.
+ *
+ * @param {Token[]} tokens Micromark tokens.
+ * @param {TokenType[]} types Types to allow.
+ * @param {boolean} [htmlFlow] Whether to include htmlFlow content.
+ * @returns {Token[]} Filtered tokens.
+ */
+function filterByTypes(tokens, types, htmlFlow) {
+  const predicate = (token) => types.includes(token.type) && (htmlFlow || !inHtmlFlow(token));
+  const flatTokens = tokens[flatTokensSymbol];
+  if (flatTokens) {
+    return flatTokens.filter(predicate);
+  }
+  return filterByPredicate(tokens, predicate);
+}
+
+/**
+ * Gets the blockquote prefix text (if any) for the specified line number.
+ *
+ * @param {Token[]} tokens Micromark tokens.
+ * @param {number} lineNumber Line number to examine.
+ * @param {number} [count] Number of times to repeat.
+ * @returns {string} Blockquote prefix text.
+ */
+function getBlockQuotePrefixText(tokens, lineNumber, count = 1) {
+  return filterByTypes(tokens, [ "blockQuotePrefix", "linePrefix" ])
+    .filter((prefix) => prefix.startLine === lineNumber)
+    .map((prefix) => prefix.text)
+    .join("")
+    .trimEnd()
+    // eslint-disable-next-line unicorn/prefer-spread
+    .concat("\n")
+    .repeat(count);
+};
+
+/**
+ * Gets a list of nested Micromark token descendants by type path.
+ *
+ * @param {Token|Token[]} parent Micromark token parent or parents.
+ * @param {(TokenType|TokenType[])[]} typePath Micromark token type path.
+ * @returns {Token[]} Micromark token descendants.
+ */
+function getDescendantsByType(parent, typePath) {
+  let tokens = Array.isArray(parent) ? parent : [ parent ];
+  for (const type of typePath) {
+    const predicate = (token) => Array.isArray(type) ? type.includes(token.type) : (type === token.type);
+    tokens = tokens.flatMap((t) => t.children.filter(predicate));
+  }
+  return tokens;
+}
+
+/**
+ * Gets the heading level of a Micromark heading tokan.
+ *
+ * @param {Token} heading Micromark heading token.
+ * @returns {number} Heading level.
+ */
+function getHeadingLevel(heading) {
+  let level = 1;
+  const headingSequence = heading.children.find(
+    (child) => [ "atxHeadingSequence", "setextHeadingLine" ].includes(child.type)
+  );
+  // @ts-ignore
+  const { text } = headingSequence;
+  if (text[0] === "#") {
+    level = Math.min(text.length, 6);
+  } else if (text[0] === "-") {
+    level = 2;
+  }
+  return level;
+}
+
+/**
+ * Gets the heading style of a Micromark heading tokan.
+ *
+ * @param {Token} heading Micromark heading token.
+ * @returns {"atx" | "atx_closed" | "setext"} Heading style.
+ */
+function getHeadingStyle(heading) {
+  if (heading.type === "setextHeading") {
+    return "setext";
+  }
+  const atxHeadingSequenceLength = heading.children.filter(
+    (child) => child.type === "atxHeadingSequence"
+  ).length;
+  if (atxHeadingSequenceLength === 1) {
+    return "atx";
+  }
+  return "atx_closed";
+}
+
+/**
+ * Gets the heading text of a Micromark heading token.
+ *
+ * @param {Token} heading Micromark heading token.
+ * @returns {string} Heading text.
+ */
+function getHeadingText(heading) {
+  const headingTexts = getDescendantsByType(heading, [ [ "atxHeadingText", "setextHeadingText" ] ]);
+  return headingTexts[0]?.text.replace(/[\r\n]+/g, " ") || "";
+}
+
+/**
+ * HTML tag information.
+ *
+ * @typedef {Object} HtmlTagInfo
+ * @property {boolean} close True iff close tag.
+ * @property {string} name Tag name.
+ */
+
+/**
+ * Gets information about the tag in an HTML token.
+ *
+ * @param {Token} token Micromark token.
+ * @returns {HtmlTagInfo | 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;
+}
+
+/**
+ * Gets the nearest parent of the specified type for a Micromark token.
+ *
+ * @param {Token} token Micromark token.
+ * @param {TokenType[]} types Types to allow.
+ * @returns {Token | null} Parent token.
+ */
+function getParentOfType(token, types) {
+  /** @type {Token | null} */
+  let current = token;
+  while ((current = current.parent) && !types.includes(current.type)) {
+    // Empty
+  }
+  return current;
+}
+
+/**
+ * Set containing token types that do not contain content.
+ *
+ * @type {Set<TokenType>}
+ */
+const nonContentTokens = new Set([
+  "blockQuoteMarker",
+  "blockQuotePrefix",
+  "blockQuotePrefixWhitespace",
+  "lineEnding",
+  "lineEndingBlank",
+  "linePrefix",
+  "listItemIndent"
+]);
+
+module.exports = {
+  addRangeToSet,
+  filterByPredicate,
+  filterByTypes,
+  getBlockQuotePrefixText,
+  getDescendantsByType,
+  getHeadingLevel,
+  getHeadingStyle,
+  getHeadingText,
+  getHtmlTagInfo,
+  getParentOfType,
+  inHtmlFlow,
+  isHtmlFlowComment,
+  nonContentTokens
+};

package/helpers/micromark-parse.cjs

@@ -0,0 +1,313 @@
+// @ts-check
+
+"use strict";
+
+const micromark = require("markdownlint-micromark");
+const { isHtmlFlowComment } = require("./micromark-helpers.cjs");
+const { flatTokensSymbol, htmlFlowSymbol, newLineRe } = require("./shared.js");
+
+/** @typedef {import("markdownlint-micromark").Construct} Construct */
+/** @typedef {import("markdownlint-micromark").Event} Event */
+/** @typedef {import("markdownlint-micromark").ParseOptions} MicromarkParseOptions */
+/** @typedef {import("markdownlint-micromark").State} State */
+/** @typedef {import("markdownlint-micromark").Token} Token */
+/** @typedef {import("markdownlint-micromark").Tokenizer} Tokenizer */
+/** @typedef {import("../lib/markdownlint.js").MicromarkToken} MicromarkToken */
+
+/**
+ * Parse options.
+ *
+ * @typedef {Object} ParseOptions
+ * @property {boolean} [freezeTokens] Whether to freeze output Tokens.
+ */
+
+/**
+ * Parses a Markdown document and returns Micromark events.
+ *
+ * @param {string} markdown Markdown document.
+ * @param {MicromarkParseOptions} [micromarkParseOptions] Options for micromark.
+ * @returns {Event[]} Micromark events.
+ */
+function getEvents(
+  markdown,
+  micromarkParseOptions = {}
+) {
+  // Customize extensions list to add useful extensions
+  const extensions = [
+    micromark.directive(),
+    micromark.gfmAutolinkLiteral(),
+    micromark.gfmFootnote(),
+    micromark.gfmTable(),
+    micromark.math(),
+    ...(micromarkParseOptions.extensions || [])
+  ];
+
+  // // Shim labelEnd to identify undefined link labels
+  /** @type {Event[][]} */
+  const artificialEventLists = [];
+  /** @type {Construct} */
+  const labelEnd =
+    // @ts-ignore
+    micromark.labelEnd;
+  const tokenizeOriginal = labelEnd.tokenize;
+
+  /** @type {Tokenizer} */
+  function tokenizeShim(effects, okOriginal, nokOriginal) {
+    // eslint-disable-next-line consistent-this, unicorn/no-this-assignment, no-invalid-this
+    const tokenizeContext = this;
+    const events = tokenizeContext.events;
+
+    /** @type {State} */
+    const nokShim = (code) => {
+      // Find start of label (image or link)
+      let indexStart = events.length;
+      while (--indexStart >= 0) {
+        const event = events[indexStart];
+        const [ kind, token ] = event;
+        if (kind === "enter") {
+          const { type } = token;
+          if ((type === "labelImage") || (type === "labelLink")) {
+            // Found it
+            break;
+          }
+        }
+      }
+
+      // If found...
+      if (indexStart >= 0) {
+        // Create artificial enter/exit events and replicate all data/lineEnding events within
+        const eventStart = events[indexStart];
+        const [ , eventStartToken ] = eventStart;
+        const eventEnd = events[events.length - 1];
+        const [ , eventEndToken ] = eventEnd;
+        /** @type {Token} */
+        const undefinedReferenceType = {
+          "type": "undefinedReferenceShortcut",
+          "start": eventStartToken.start,
+          "end": eventEndToken.end
+        };
+        /** @type {Token} */
+        const undefinedReference = {
+          "type": "undefinedReference",
+          "start": eventStartToken.start,
+          "end": eventEndToken.end
+        };
+        const eventsToReplicate = events
+          .slice(indexStart)
+          .filter((event) => {
+            const [ , eventToken ] = event;
+            const { type } = eventToken;
+            return (type === "data") || (type === "lineEnding");
+          });
+
+        // Determine the type of the undefined reference
+        const previousUndefinedEvent = (artificialEventLists.length > 0) && artificialEventLists[artificialEventLists.length - 1][0];
+        const previousUndefinedToken = previousUndefinedEvent && previousUndefinedEvent[1];
+        if (
+          previousUndefinedToken &&
+          (previousUndefinedToken.end.line === undefinedReferenceType.start.line) &&
+          (previousUndefinedToken.end.column === undefinedReferenceType.start.column)
+        ) {
+          // Previous undefined reference event is immediately before this one
+          if (eventsToReplicate.length === 0) {
+            // The pair represent a collapsed reference (ex: [...][])
+            previousUndefinedToken.type = "undefinedReferenceCollapsed";
+            previousUndefinedToken.end = eventEndToken.end;
+          } else {
+            // The pair represent a full reference (ex: [...][...])
+            undefinedReferenceType.type = "undefinedReferenceFull";
+            undefinedReferenceType.start = previousUndefinedToken.start;
+            artificialEventLists.pop();
+          }
+        }
+
+        // Create artificial event list and replicate content
+        const text = eventsToReplicate
+          .filter((event) => event[0] === "enter")
+          .map((event) => tokenizeContext.sliceSerialize(event[1]))
+          .join("")
+          .trim();
+        if ((text.length > 0) && !text.includes("]")) {
+          /** @type {Event[]} */
+          const artificialEvents = [];
+          artificialEvents.push(
+            [ "enter", undefinedReferenceType, tokenizeContext ],
+            [ "enter", undefinedReference, tokenizeContext ]
+          );
+          for (const event of eventsToReplicate) {
+            const [ kind, token ] = event;
+            // Copy token because the current object will get modified by the parser
+            artificialEvents.push([ kind, { ...token }, tokenizeContext ]);
+          }
+          artificialEvents.push(
+            [ "exit", undefinedReference, tokenizeContext ],
+            [ "exit", undefinedReferenceType, tokenizeContext ]
+          );
+          artificialEventLists.push(artificialEvents);
+        }
+      }
+
+      // Continue with original behavior
+      return nokOriginal(code);
+    };
+
+    // Shim nok handler of labelEnd's tokenize
+    return tokenizeOriginal.call(tokenizeContext, effects, okOriginal, nokShim);
+  }
+
+  try {
+    // Shim labelEnd behavior to detect undefined references
+    labelEnd.tokenize = tokenizeShim;
+
+    // Use micromark to parse document into Events
+    const encoding = undefined;
+    const eol = true;
+    const parseContext = micromark.parse({ ...micromarkParseOptions, extensions });
+    const chunks = micromark.preprocess()(markdown, encoding, eol);
+    const events = micromark.postprocess(parseContext.document().write(chunks));
+
+    // Append artificial events and return all events
+    // eslint-disable-next-line unicorn/prefer-spread
+    return events.concat(...artificialEventLists);
+  } finally {
+    // Restore shimmed labelEnd behavior
+    labelEnd.tokenize = tokenizeOriginal;
+  }
+}
+
+/**
+ * Parses a Markdown document and returns micromark tokens (internal).
+ *
+ * @param {string} markdown Markdown document.
+ * @param {ParseOptions} [parseOptions] Options.
+ * @param {MicromarkParseOptions} [micromarkParseOptions] Options for micromark.
+ * @param {number} [lineDelta] Offset for start/end line.
+ * @param {MicromarkToken} [ancestor] Parent of top-most tokens.
+ * @returns {MicromarkToken[]} Micromark tokens.
+ */
+function parseInternal(
+  markdown,
+  parseOptions = {},
+  micromarkParseOptions = {},
+  lineDelta = 0,
+  ancestor = undefined
+) {
+  // Get options
+  const freezeTokens = Boolean(parseOptions.freezeTokens);
+
+  // Use micromark to parse document into Events
+  const events = getEvents(markdown, micromarkParseOptions);
+
+  // Create Token objects
+  const document = [];
+  let flatTokens = [];
+  /** @type {MicromarkToken} */
+  const root = {
+    "type": "data",
+    "startLine": -1,
+    "startColumn": -1,
+    "endLine": -1,
+    "endColumn": -1,
+    "text": "ROOT",
+    "children": document,
+    "parent": null
+  };
+  const history = [ root ];
+  let current = root;
+  // eslint-disable-next-line jsdoc/valid-types
+  /** @type MicromarkParseOptions | null */
+  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") && !skipHtmlFlowChildren) {
+      const previous = current;
+      history.push(previous);
+      current = {
+        type,
+        "startLine": startLine + lineDelta,
+        startColumn,
+        "endLine": endLine + lineDelta,
+        endColumn,
+        text,
+        "children": [],
+        "parent": ((previous === root) ? (ancestor || null) : previous)
+      };
+      if (ancestor) {
+        Object.defineProperty(current, htmlFlowSymbol, { "value": true });
+      }
+      previous.children.push(current);
+      flatTokens.push(current);
+      if ((current.type === "htmlFlow") && !isHtmlFlowComment(current)) {
+        skipHtmlFlowChildren = true;
+        if (!reparseOptions || !lines) {
+          reparseOptions = {
+            ...micromarkParseOptions,
+            "extensions": [
+              {
+                "disable": {
+                  "null": [ "codeIndented", "htmlFlow" ]
+                }
+              }
+            ]
+          };
+          lines = markdown.split(newLineRe);
+        }
+        const reparseMarkdown = lines
+          .slice(current.startLine - 1, current.endLine)
+          .join("\n");
+        const tokens = parseInternal(
+          reparseMarkdown,
+          parseOptions,
+          reparseOptions,
+          current.startLine - 1,
+          current
+        );
+        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) {
+        if (freezeTokens) {
+          Object.freeze(current.children);
+          Object.freeze(current);
+        }
+        // @ts-ignore
+        current = history.pop();
+      }
+    }
+  }
+
+  // Return document
+  Object.defineProperty(document, flatTokensSymbol, { "value": flatTokens });
+  if (freezeTokens) {
+    Object.freeze(document);
+  }
+  return document;
+}
+
+/**
+ * Parses a Markdown document and returns micromark tokens.
+ *
+ * @param {string} markdown Markdown document.
+ * @param {ParseOptions} [parseOptions] Options.
+ * @returns {MicromarkToken[]} Micromark tokens.
+ */
+function parse(markdown, parseOptions) {
+  return parseInternal(markdown, parseOptions);
+}
+
+module.exports = {
+  getEvents,
+  parse
+};

package/helpers/package.json

@@ -1,9 +1,12 @@
 {
   "name": "markdownlint-rule-helpers",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "A collection of markdownlint helper functions for custom rules",
   "main": "./helpers.js",
-  "exports": "./helpers.js",
+  "exports": {
+    ".": "./helpers.js",
+    "./micromark": "./micromark-helpers.cjs"
+  },
   "author": "David Anson (https://dlaa.me/)",
   "license": "MIT",
   "homepage": "https://github.com/DavidAnson/markdownlint",

package/helpers/shared.js

@@ -2,6 +2,12 @@
 
 "use strict";
 
+// Symbol for identifing the flat tokens array from micromark parse
+module.exports.flatTokensSymbol = Symbol("flat-tokens");
+
+// Symbol for identifying the htmlFlow token from micromark parse
+module.exports.htmlFlowSymbol = Symbol("html-flow");
+
 // 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/helpers/test.cjs

@@ -0,0 +1,28 @@
+// @ts-check
+
+"use strict";
+
+// eslint-disable-next-line n/no-extraneous-require
+const test = require("ava").default;
+const { "exports": packageExports, name } = require("../helpers/package.json");
+
+const exportMappings = new Map([
+  [ ".", "../helpers/helpers.js" ],
+  [ "./micromark", "../helpers/micromark-helpers.cjs" ]
+]);
+
+test("exportMappings", (t) => {
+  t.deepEqual(
+    Object.keys(packageExports),
+    [ ...exportMappings.keys() ]
+  );
+});
+
+for (const [ exportName, exportPath ] of exportMappings) {
+  test(exportName, (t) => {
+    t.is(
+      require(exportName.replace(/^\./u, name)),
+      require(exportPath)
+    );
+  });
+}

package/lib/cache.js

@@ -3,11 +3,10 @@
 "use strict";
 
 const helpers = require("../helpers");
-const { filterByTypes } = require("../helpers/micromark.cjs");
+const { filterByTypes } = require("../helpers/micromark-helpers.cjs");
 
 /** @type {Map<string, object>} */
 const map = new Map();
-// eslint-disable-next-line no-undef-init
 let params = undefined;
 
 /**
@@ -46,7 +45,8 @@ function getCached(name, getValue) {
  */
 function filterByTypesCached(types, htmlFlow) {
   return getCached(
-    types.join("|"),
+    // eslint-disable-next-line prefer-rest-params
+    JSON.stringify(arguments),
     () => filterByTypes(params.parsers.micromark.tokens, types, htmlFlow)
   );
 }