markdownlint 0.34.0 → 0.35.0

package/helpers/micromark.cjs

@@ -11,12 +11,23 @@ const {
 const { newLineRe } = require("./shared.js");
 
 const flatTokensSymbol = Symbol("flat-tokens");
+const reparseSymbol = Symbol("reparse");
 
 /** @typedef {import("markdownlint-micromark").Event} Event */
 /** @typedef {import("markdownlint-micromark").ParseOptions} ParseOptions */
 /** @typedef {import("markdownlint-micromark").TokenType} TokenType */
 /** @typedef {import("../lib/markdownlint.js").MicromarkToken} Token */
 
+/**
+ * Determines if a Micromark token is within an htmlFlow.
+ *
+ * @param {Token} token Micromark token.
+ * @returns {boolean} True iff the token is within an htmlFlow.
+ */
+function inHtmlFlow(token) {
+  return token[reparseSymbol];
+}
+
 /**
  * Returns whether a token is an htmlFlow type containing an HTML comment.
  *
@@ -145,6 +156,9 @@ function micromarkParseWithOffset(
         "children": [],
         "parent": ((previous === root) ? (ancestor || null) : previous)
       };
+      if (ancestor) {
+        Object.defineProperty(current, reparseSymbol, { "value": true });
+      }
       previous.children.push(current);
       flatTokens.push(current);
       if ((current.type === "htmlFlow") && !isHtmlFlowComment(current)) {
@@ -217,6 +231,20 @@ function micromarkParse(
   );
 }
 
+/**
+ * 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.
@@ -277,10 +305,12 @@ function filterByPredicate(tokens, allowed, transformChildren) {
  *
  * @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) {
-  const predicate = (token) => types.includes(token.type);
+function filterByTypes(tokens, types, htmlFlow) {
+  const predicate = (token) =>
+    (htmlFlow || !inHtmlFlow(token)) && types.includes(token.type);
   const flatTokens = tokens[flatTokensSymbol];
   if (flatTokens) {
     return flatTokens.filter(predicate);
@@ -288,6 +318,46 @@ function filterByTypes(tokens, types) {
   return filterByPredicate(tokens, predicate);
 }
 
+/**
+ * Gets a list of nested Micromark token descendants by type path.
+ *
+ * @param {Token|Token[]} parent Micromark token parent or parents.
+ * @param {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) {
+    tokens = tokens.flatMap((t) => t.children).filter((t) => t.type === type);
+  }
+  return tokens;
+}
+
+// eslint-disable-next-line jsdoc/valid-types
+/** @typedef {readonly string[]} ReadonlyStringArray */
+
+/**
+ * Gets the line/column/length exclusions for a Micromark token.
+ *
+ * @param {ReadonlyStringArray} lines File/string lines.
+ * @param {Token} token Micromark token.
+ * @returns {number[][]} Exclusions (line number, start column, length).
+ */
+function getExclusionsForToken(lines, token) {
+  const exclusions = [];
+  const { endColumn, endLine, startColumn, startLine } = token;
+  for (let lineNumber = startLine; lineNumber <= endLine; lineNumber++) {
+    const start = (lineNumber === startLine) ? startColumn : 1;
+    const end = (lineNumber === endLine) ? endColumn : lines[lineNumber - 1].length;
+    exclusions.push([
+      lineNumber,
+      start,
+      end - start + 1
+    ]);
+  }
+  return exclusions;
+}
+
 /**
  * Gets the heading level of a Micromark heading tokan.
  *
@@ -309,6 +379,40 @@ function getHeadingLevel(heading) {
   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 = filterByTypes(
+    heading.children,
+    [ "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 = filterByTypes(
+    heading.children,
+    [ "atxHeadingText", "setextHeadingText" ]
+  );
+  return headingTexts[0]?.text.replace(/[\r\n]+/g, " ") || "";
+}
+
 /**
  * HTML tag information.
  *
@@ -367,16 +471,6 @@ function getTokenTextByType(tokens, type) {
   return (filtered.length > 0) ? filtered[0].text : null;
 }
 
-/**
- * Determines if a Micromark token has an htmlFlow-type parent.
- *
- * @param {Token} token Micromark token.
- * @returns {boolean} True iff the token has an htmlFlow-type parent.
- */
-function inHtmlFlow(token) {
-  return getTokenParentOfType(token, [ "htmlFlow" ]) !== null;
-}
-
 /**
  * Determines a list of Micromark tokens matches and returns a subset.
  *
@@ -430,9 +524,14 @@ const nonContentTokens = new Set([
 
 module.exports = {
   "parse": micromarkParse,
+  addRangeToSet,
   filterByPredicate,
   filterByTypes,
+  getDescendantsByType,
+  getExclusionsForToken,
   getHeadingLevel,
+  getHeadingStyle,
+  getHeadingText,
   getHtmlTagInfo,
   getMicromarkEvents,
   getTokenParentOfType,

package/helpers/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markdownlint-rule-helpers",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "A collection of markdownlint helper functions for custom rules",
   "main": "./helpers.js",
   "exports": "./helpers.js",

package/lib/cache.js

@@ -2,20 +2,69 @@
 
 "use strict";
 
+const helpers = require("../helpers");
+const { filterByTypes } = require("../helpers/micromark.cjs");
+
+/** @type {Map<string, object>} */
 const map = new Map();
+// eslint-disable-next-line no-undef-init
+let params = undefined;
+
+/**
+ * Initializes (resets) the cache.
+ *
+ * @param {import("./markdownlint").RuleParams} [p] Rule parameters object.
+ * @returns {void}
+ */
+function initialize(p) {
+  map.clear();
+  params = p;
+}
 
-module.exports.set = (keyValuePairs) => {
-  for (const [ key, value ] of Object.entries(keyValuePairs)) {
-    map.set(key, value);
+/**
+ * Gets a cached object value - computes it and caches it.
+ *
+ * @param {string} name Cache object name.
+ * @param {Function} getValue Getter for object value.
+ * @returns {Object} Object value.
+ */
+function getCached(name, getValue) {
+  if (map.has(name)) {
+    return map.get(name);
   }
+  const value = getValue();
+  map.set(name, value);
+  return value;
+}
+
+/**
+ * Filters a list of Micromark tokens by type and caches the result.
+ *
+ * @param {import("./markdownlint").MicromarkTokenType[]} types Types to allow.
+ * @param {boolean} [htmlFlow] Whether to include htmlFlow content.
+ * @returns {import("./markdownlint").MicromarkToken[]} Filtered tokens.
+ */
+function filterByTypesCached(types, htmlFlow) {
+  return getCached(
+    types.join("|"),
+    () => filterByTypes(params.parsers.micromark.tokens, types, htmlFlow)
+  );
+}
+
+/**
+ * Gets a reference link and image data object.
+ *
+ * @returns {Object} Reference link and image data object.
+ */
+function getReferenceLinkImageData() {
+  return getCached(
+    getReferenceLinkImageData.name,
+    () => helpers.getReferenceLinkImageData(params.parsers.micromark.tokens)
+  );
+}
+
+module.exports = {
+  initialize,
+  filterByTypesCached,
+  getReferenceLinkImageData
 };
-module.exports.clear = () => map.clear();
-
-module.exports.codeBlockAndSpanRanges =
-  () => map.get("codeBlockAndSpanRanges");
-module.exports.flattenedLists =
-  () => map.get("flattenedLists");
-module.exports.lineMetadata =
-  () => map.get("lineMetadata");
-module.exports.referenceLinkImageData =
-  () => map.get("referenceLinkImageData");