markdownlint 0.33.0 → 0.35.0

package/helpers/micromark.cjs

@@ -4,27 +4,29 @@
 
 // @ts-ignore
 const {
-  directive, gfmAutolinkLiteral, gfmFootnote, gfmTable, math, parse,
-  postprocess, preprocess
+  directive, gfmAutolinkLiteral, gfmFootnote, gfmTable, math,
+  parse, postprocess, preprocess
   // @ts-ignore
 } = require("markdownlint-micromark");
 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 */
 
 /**
- * Markdown token.
+ * Determines if a Micromark token is within an htmlFlow.
  *
- * @typedef {Object} Token
- * @property {string} type Token type.
- * @property {number} startLine Start line (1-based).
- * @property {number} startColumn Start column (1-based).
- * @property {number} endLine End line (1-based).
- * @property {number} endColumn End column (1-based).
- * @property {string} text Token text.
- * @property {Token[]} children Child tokens.
- * @property {Token | null} parent Parent token.
+ * @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.
@@ -59,9 +61,9 @@ function isHtmlFlowComment(token) {
  * Parses a Markdown document and returns Micromark events.
  *
  * @param {string} markdown Markdown document.
- * @param {Object} [micromarkOptions] Options for micromark.
+ * @param {ParseOptions} [micromarkOptions] Options for micromark.
  * @param {boolean} [referencesDefined] Treat references as defined.
- * @returns {Object[]} Micromark events.
+ * @returns {Event[]} Micromark events.
  */
 function getMicromarkEvents(
   markdown,
@@ -96,7 +98,7 @@ function getMicromarkEvents(
  * Parses a Markdown document and returns (frozen) tokens.
  *
  * @param {string} markdown Markdown document.
- * @param {Object} micromarkOptions Options for micromark.
+ * @param {ParseOptions} micromarkOptions Options for micromark.
  * @param {boolean} referencesDefined Treat references as defined.
  * @param {number} lineDelta Offset to apply to start/end line.
  * @param {Token} [ancestor] Parent of top-most tokens.
@@ -119,7 +121,7 @@ function micromarkParseWithOffset(
   let flatTokens = [];
   /** @type {Token} */
   const root = {
-    "type": "ROOT",
+    "type": "data",
     "startLine": -1,
     "startColumn": -1,
     "endLine": -1,
@@ -130,6 +132,8 @@ function micromarkParseWithOffset(
   };
   const history = [ root ];
   let current = root;
+  // eslint-disable-next-line jsdoc/valid-types
+  /** @type ParseOptions | null */
   let reparseOptions = null;
   let lines = null;
   let skipHtmlFlowChildren = false;
@@ -152,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)) {
@@ -207,7 +214,7 @@ function micromarkParseWithOffset(
  * Parses a Markdown document and returns (frozen) tokens.
  *
  * @param {string} markdown Markdown document.
- * @param {Object} [micromarkOptions] Options for micromark.
+ * @param {ParseOptions} [micromarkOptions] Options for micromark.
  * @param {boolean} [referencesDefined] Treat references as defined.
  * @returns {Token[]} Micromark tokens (frozen).
  */
@@ -224,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.
@@ -283,11 +304,13 @@ function filterByPredicate(tokens, allowed, transformChildren) {
  * Filter a list of Micromark tokens by type.
  *
  * @param {Token[]} tokens Micromark tokens.
- * @param {string[]} types Types to allow.
+ * @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);
@@ -295,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.
  *
@@ -316,11 +379,53 @@ 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.
+ *
+ * @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 {Object | null} HTML tag information.
+ * @returns {HtmlTagInfo | null} HTML tag information.
  */
 function getHtmlTagInfo(token) {
   const htmlTagNameRe = /^<([^!>][^/\s>]*)/;
@@ -342,7 +447,7 @@ function getHtmlTagInfo(token) {
  * Gets the nearest parent of the specified type for a Micromark token.
  *
  * @param {Token} token Micromark token.
- * @param {string[]} types Types to allow.
+ * @param {TokenType[]} types Types to allow.
  * @returns {Token | null} Parent token.
  */
 function getTokenParentOfType(token, types) {
@@ -358,7 +463,7 @@ function getTokenParentOfType(token, types) {
  * Get the text of the first match from a list of Micromark tokens by type.
  *
  * @param {Token[]} tokens Micromark tokens.
- * @param {string} type Types to match.
+ * @param {TokenType} type Type to match.
  * @returns {string | null} Text of token.
  */
 function getTokenTextByType(tokens, type) {
@@ -366,22 +471,12 @@ 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.
  *
  * @param {Token[]} tokens Micromark tokens.
- * @param {string[]} matchTypes Types to match.
- * @param {string[]} [resultTypes] Types to return.
+ * @param {TokenType[]} matchTypes Types to match.
+ * @param {TokenType[]} [resultTypes] Types to return.
  * @returns {Token[] | null} Matching tokens.
  */
 function matchAndGetTokensByType(tokens, matchTypes, resultTypes) {
@@ -405,23 +500,45 @@ function matchAndGetTokensByType(tokens, matchTypes, resultTypes) {
  * Returns the specified token iff it is of the desired type.
  *
  * @param {Token} token Micromark token candidate.
- * @param {string} type Desired type.
+ * @param {TokenType} type Desired type.
  * @returns {Token | null} Token instance.
  */
 function tokenIfType(token, type) {
   return (token && (token.type === type)) ? token : null;
 }
 
+/**
+ * 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 = {
   "parse": micromarkParse,
+  addRangeToSet,
   filterByPredicate,
   filterByTypes,
+  getDescendantsByType,
+  getExclusionsForToken,
   getHeadingLevel,
+  getHeadingStyle,
+  getHeadingText,
   getHtmlTagInfo,
   getMicromarkEvents,
   getTokenParentOfType,
   getTokenTextByType,
   inHtmlFlow,
+  isHtmlFlowComment,
   matchAndGetTokensByType,
+  nonContentTokens,
   tokenIfType
 };

package/helpers/package.json

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

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");