markdownlint 0.29.0 → 0.31.0

package/helpers/helpers.js

@@ -4,9 +4,7 @@
 
 const micromark = require("./micromark.cjs");
 
-// Regular expression for matching common newline characters
-// See NEWLINES_RE in markdown-it/lib/rules_core/normalize.js
-const newLineRe = /\r\n?|\n/g;
+const { newLineRe } = require("./shared.js");
 module.exports.newLineRe = newLineRe;
 
 // Regular expression for matching common front matter (YAML and TOML)
@@ -20,17 +18,10 @@ const inlineCommentStartRe =
   /(<!--\s*markdownlint-(disable|enable|capture|restore|disable-file|enable-file|disable-line|disable-next-line|configure-file))(?:\s|-->)/gi;
 module.exports.inlineCommentStartRe = inlineCommentStartRe;
 
-// Regular expression for matching HTML elements
-const htmlElementRe = /<(([A-Za-z][A-Za-z\d-]*)(?:\s[^`>]*)?)\/?>/g;
-module.exports.htmlElementRe = htmlElementRe;
-
 // Regular expressions for range matching
 module.exports.listItemMarkerRe = /^([\s>]*)(?:[*+-]|\d+[.)])\s+/;
 module.exports.orderedListItemMarkerRe = /^[\s>]*0*(\d+)[.)]/;
 
-// Regular expression for all instances of emphasis markers
-const emphasisMarkersRe = /[_*]/g;
-
 // Regular expression for blockquote prefixes
 const blockquotePrefixRe = /^[>\s]*/;
 module.exports.blockquotePrefixRe = blockquotePrefixRe;
@@ -39,6 +30,16 @@ module.exports.blockquotePrefixRe = blockquotePrefixRe;
 const linkReferenceDefinitionRe = /^ {0,3}\[([^\]]*[^\\])\]:/;
 module.exports.linkReferenceDefinitionRe = linkReferenceDefinitionRe;
 
+// Regular expression for identifying an HTML entity at the end of a line
+module.exports.endOfLineHtmlEntityRe =
+  // eslint-disable-next-line max-len
+  /&(?:#\d+|#[xX][\da-fA-F]+|[a-zA-Z]{2,31}|blk\d{2}|emsp1[34]|frac\d{2}|sup\d|there4);$/;
+
+// Regular expression for identifying a GitHub emoji code at the end of a line
+module.exports.endOfLineGemojiCodeRe =
+  // eslint-disable-next-line max-len
+  /:(?:[abmovx]|[-+]1|100|1234|(?:1st|2nd|3rd)_place_medal|8ball|clock\d{1,4}|e-mail|non-potable_water|o2|t-rex|u5272|u5408|u55b6|u6307|u6708|u6709|u6e80|u7121|u7533|u7981|u7a7a|[a-z]{2,15}2?|[a-z]{1,14}(?:_[a-z\d]{1,16})+):$/;
+
 // All punctuation characters (normal and full-width)
 const allPunctuation = ".,;:!?。，；：！？";
 module.exports.allPunctuation = allPunctuation;
@@ -46,25 +47,82 @@ module.exports.allPunctuation = allPunctuation;
 // All punctuation characters without question mark (normal and full-width)
 module.exports.allPunctuationNoQuestion = allPunctuation.replace(/[?？]/gu, "");
 
-// Returns true iff the input is a number
-module.exports.isNumber = function isNumber(obj) {
+/**
+ * Returns true iff the input is a Number.
+ *
+ * @param {Object} obj Object of unknown type.
+ * @returns {boolean} True iff obj is a Number.
+ */
+function isNumber(obj) {
   return typeof obj === "number";
-};
+}
+module.exports.isNumber = isNumber;
 
-// Returns true iff the input is a string
-module.exports.isString = function isString(obj) {
+/**
+ * Returns true iff the input is a String.
+ *
+ * @param {Object} obj Object of unknown type.
+ * @returns {boolean} True iff obj is a String.
+ */
+function isString(obj) {
   return typeof obj === "string";
-};
+}
+module.exports.isString = isString;
 
-// Returns true iff the input string is empty
-module.exports.isEmptyString = function isEmptyString(str) {
+/**
+ * Returns true iff the input String is empty.
+ *
+ * @param {string} str String of unknown length.
+ * @returns {boolean} True iff the input String is empty.
+ */
+function isEmptyString(str) {
   return str.length === 0;
-};
+}
+module.exports.isEmptyString = isEmptyString;
 
-// Returns true iff the input is an object
-module.exports.isObject = function isObject(obj) {
-  return (obj !== null) && (typeof obj === "object") && !Array.isArray(obj);
-};
+/**
+ * Returns true iff the input is an Object.
+ *
+ * @param {Object} obj Object of unknown type.
+ * @returns {boolean} True iff obj is an Object.
+ */
+function isObject(obj) {
+  return !!obj && (typeof obj === "object") && !Array.isArray(obj);
+}
+module.exports.isObject = isObject;
+
+/**
+ * Returns true iff the input is a URL.
+ *
+ * @param {Object} obj Object of unknown type.
+ * @returns {boolean} True iff obj is a URL.
+ */
+function isUrl(obj) {
+  return !!obj && (Object.getPrototypeOf(obj) === URL.prototype);
+}
+module.exports.isUrl = isUrl;
+
+/**
+ * Clones the input if it is an Array.
+ *
+ * @param {Object} arr Object of unknown type.
+ * @returns {Object} Clone of obj iff obj is an Array.
+ */
+function cloneIfArray(arr) {
+  return Array.isArray(arr) ? [ ...arr ] : arr;
+}
+module.exports.cloneIfArray = cloneIfArray;
+
+/**
+ * Clones the input if it is a URL.
+ *
+ * @param {Object} url Object of unknown type.
+ * @returns {Object} Clone of obj iff obj is a URL.
+ */
+function cloneIfUrl(url) {
+  return isUrl(url) ? new URL(url) : url;
+}
+module.exports.cloneIfUrl = cloneIfUrl;
 
 /**
  * Returns true iff the input line is blank (contains nothing, whitespace, or
@@ -264,12 +322,18 @@ module.exports.unorderedListStyleFor = function unorderedListStyleFor(token) {
   }
 };
 
+/**
+ * @callback TokenCallback
+ * @param {MarkdownItToken} token Current token.
+ * @returns {void}
+ */
+
 /**
  * Calls the provided function for each matching token.
  *
  * @param {Object} params RuleParams instance.
  * @param {string} type Token type identifier.
- * @param {Function} handler Callback function.
+ * @param {TokenCallback} handler Callback function.
  * @returns {void}
  */
 function filterTokens(params, type, handler) {
@@ -282,24 +346,18 @@ function filterTokens(params, type, handler) {
 module.exports.filterTokens = filterTokens;
 
 /**
- * Returns whether a token is a math block (created by markdown-it-texmath).
- *
- * @param {Object} token MarkdownItToken instance.
- * @returns {boolean} True iff token is a math block.
+ * @typedef {Array} LineMetadata
  */
-function isMathBlock(token) {
-  return (
-    ((token.tag === "$$") || (token.tag === "math")) &&
-    token.type.startsWith("math_block") &&
-    !token.type.endsWith("_end")
-  );
-}
-module.exports.isMathBlock = isMathBlock;
 
-// Get line metadata array
-module.exports.getLineMetadata = function getLineMetadata(params) {
+/**
+ * Gets a line metadata array.
+ *
+ * @param {Object} params RuleParams instance.
+ * @returns {LineMetadata} Line metadata.
+ */
+function getLineMetadata(params) {
   const lineMetadata = params.lines.map(
-    (line, index) => [ line, index, false, 0, false, false, false, false ]
+    (line, index) => [ line, index, false, 0, false, false, false ]
   );
   filterTokens(params, "fence", (token) => {
     lineMetadata[token.map[0]][3] = 1;
@@ -328,24 +386,33 @@ module.exports.getLineMetadata = function getLineMetadata(params) {
   filterTokens(params, "hr", (token) => {
     lineMetadata[token.map[0]][6] = true;
   });
-  for (const token of params.parsers.markdownit.tokens.filter(isMathBlock)) {
-    for (let i = token.map[0]; i < token.map[1]; i++) {
-      lineMetadata[i][7] = true;
-    }
-  }
   return lineMetadata;
-};
+}
+module.exports.getLineMetadata = getLineMetadata;
+
+/**
+ * @callback EachLineCallback
+ * @param {string} line Line content.
+ * @param {number} lineIndex Line index (0-based).
+ * @param {boolean} inCode Iff in a code block.
+ * @param {number} onFence + if open, - if closed, 0 otherwise.
+ * @param {boolean} inTable Iff in a table.
+ * @param {boolean} inItem Iff in a list item.
+ * @param {boolean} inBreak Iff in semantic break.
+ * @returns {void}
+ */
 
 /**
  * Calls the provided function for each line.
  *
- * @param {Object} lineMetadata Line metadata object.
- * @param {Function} handler Function taking (line, lineIndex, inCode, onFence,
- * inTable, inItem, inBreak, inMath).
+ * @param {LineMetadata} lineMetadata Line metadata object.
+ * @param {EachLineCallback} handler Function taking (line, lineIndex, inCode,
+ * onFence, inTable, inItem, inBreak).
  * @returns {void}
  */
 function forEachLine(lineMetadata, handler) {
   for (const metadata of lineMetadata) {
+    // @ts-ignore
     handler(...metadata);
   }
 }
@@ -402,23 +469,6 @@ module.exports.flattenLists = function flattenLists(tokens) {
   return flattenedLists;
 };
 
-/**
- * Calls the provided function for each specified inline child token.
- *
- * @param {Object} params RuleParams instance.
- * @param {string} type Token type identifier.
- * @param {Function} handler Callback function.
- * @returns {void}
- */
-function forEachInlineChild(params, type, handler) {
-  filterTokens(params, "inline", (token) => {
-    for (const child of token.children.filter((c) => c.type === type)) {
-      handler(child, token);
-    }
-  });
-}
-module.exports.forEachInlineChild = forEachInlineChild;
-
 // Calls the provided function for each heading's content
 module.exports.forEachHeading = function forEachHeading(params, handler) {
   let heading = null;
@@ -433,12 +483,21 @@ module.exports.forEachHeading = function forEachHeading(params, handler) {
   }
 };
 
+/**
+ * @callback InlineCodeSpanCallback
+ * @param {string} code Code content.
+ * @param {number} lineIndex Line index (0-based).
+ * @param {number} columnIndex Column index (0-based).
+ * @param {number} ticks Count of backticks.
+ * @returns {void}
+ */
+
 /**
  * Calls the provided function for each inline code span's content.
  *
  * @param {string} input Markdown content.
- * @param {Function} handler Callback function taking (code, lineIndex,
- * columnIndex, ticks).
+ * @param {InlineCodeSpanCallback} handler Callback function taking (code,
+ * lineIndex, columnIndex, ticks).
  * @returns {void}
  */
 function forEachInlineCodeSpan(input, handler) {
@@ -588,51 +647,6 @@ module.exports.codeBlockAndSpanRanges = (params, lineMetadata) => {
   return exclusions;
 };
 
-/**
- * Returns an array of HTML element ranges.
- *
- * @param {Object} params RuleParams instance.
- * @param {Object} lineMetadata Line metadata object.
- * @returns {number[][]} Array of ranges (lineIndex, columnIndex, length).
- */
-module.exports.htmlElementRanges = (params, lineMetadata) => {
-  const exclusions = [];
-  // Match with htmlElementRe
-  forEachLine(lineMetadata, (line, lineIndex, inCode) => {
-    let match = null;
-    // eslint-disable-next-line no-unmodified-loop-condition
-    while (!inCode && ((match = htmlElementRe.exec(line)) !== null)) {
-      exclusions.push([ lineIndex, match.index, match[0].length ]);
-    }
-  });
-  // Match with html_inline
-  forEachInlineChild(params, "html_inline", (token, parent) => {
-    const parentContent = parent.content;
-    let tokenContent = token.content;
-    const parentIndex = parentContent.indexOf(tokenContent);
-    let deltaLines = 0;
-    let indent = 0;
-    for (let i = parentIndex - 1; i >= 0; i--) {
-      if (parentContent[i] === "\n") {
-        deltaLines++;
-      } else if (deltaLines === 0) {
-        indent++;
-      }
-    }
-    let lineIndex = token.lineNumber - 1 + deltaLines;
-    do {
-      const index = tokenContent.indexOf("\n");
-      const length = (index === -1) ? tokenContent.length : index;
-      exclusions.push([ lineIndex, indent, length ]);
-      tokenContent = tokenContent.slice(length + 1);
-      lineIndex++;
-      indent = 0;
-    } while (tokenContent.length > 0);
-  });
-  // Return results
-  return exclusions;
-};
-
 /**
  * Determines whether the specified range is within another range.
  *
@@ -677,129 +691,6 @@ module.exports.frontMatterHasTitle =
       frontMatterLines.some((line) => frontMatterTitleRe.test(line));
   };
 
-/**
- * Calls the provided function for each link.
- *
- * @param {string} line Line of Markdown input.
- * @param {Function} handler Function taking (index, link, text, destination).
- * @returns {void}
- */
-function forEachLink(line, handler) {
-  // Helper to find matching close symbol for link text/destination
-  const findClosingSymbol = (index) => {
-    const begin = line[index];
-    const end = (begin === "[") ? "]" : ")";
-    let nesting = 0;
-    let escaping = false;
-    let pointy = false;
-    for (let i = index + 1; i < line.length; i++) {
-      const current = line[i];
-      if (current === "\\") {
-        escaping = !escaping;
-      } else if (!escaping && (current === begin)) {
-        nesting++;
-      } else if (!escaping && (current === end)) {
-        if (nesting > 0) {
-          nesting--;
-        } else if (!pointy) {
-          // Return index after matching close symbol
-          return i + 1;
-        }
-      } else if ((i === index + 1) && (begin === "(") && (current === "<")) {
-        pointy = true;
-      } else if (!escaping && pointy && current === ">") {
-        pointy = false;
-        nesting = 0;
-      } else {
-        escaping = false;
-      }
-    }
-    // No match found
-    return -1;
-  };
-  // Scan line for unescaped "[" character
-  let escaping = false;
-  for (let i = 0; i < line.length; i++) {
-    const current = line[i];
-    if (current === "\\") {
-      escaping = !escaping;
-    } else if (!escaping && (current === "[")) {
-      // Scan for matching close "]" of link text
-      const textEnd = findClosingSymbol(i);
-      if (textEnd !== -1) {
-        if ((line[textEnd] === "(") || (line[textEnd] === "[")) {
-          // Scan for matching close ")" or "]" of link destination
-          const destEnd = findClosingSymbol(textEnd);
-          if (destEnd !== -1) {
-            // Call handler with link text and destination
-            const link = line.slice(i, destEnd);
-            const text = line.slice(i, textEnd);
-            const dest = line.slice(textEnd, destEnd);
-            handler(i, link, text, dest);
-            i = destEnd;
-          }
-        }
-        if (i < textEnd) {
-          // Call handler with link text only
-          const text = line.slice(i, textEnd);
-          handler(i, text, text);
-          i = textEnd;
-        }
-      }
-    } else {
-      escaping = false;
-    }
-  }
-}
-module.exports.forEachLink = forEachLink;
-
-/**
- * Returns a list of emphasis markers in code spans and links.
- *
- * @param {Object} params RuleParams instance.
- * @returns {number[][]} List of markers.
- */
-function emphasisMarkersInContent(params) {
-  const { lines } = params;
-  const byLine = new Array(lines.length);
-  // Search links
-  for (const [ tokenLineIndex, tokenLine ] of lines.entries()) {
-    const inLine = [];
-    forEachLink(tokenLine, (index, match) => {
-      let markerMatch = null;
-      while ((markerMatch = emphasisMarkersRe.exec(match))) {
-        inLine.push(index + markerMatch.index);
-      }
-    });
-    byLine[tokenLineIndex] = inLine;
-  }
-  // Search code spans
-  filterTokens(params, "inline", (token) => {
-    const { children, lineNumber, map } = token;
-    if (children.some((child) => child.type === "code_inline")) {
-      const tokenLines = lines.slice(map[0], map[1]);
-      forEachInlineCodeSpan(
-        tokenLines.join("\n"),
-        (code, lineIndex, column, tickCount) => {
-          const codeLines = code.split(newLineRe);
-          for (const [ codeLineIndex, codeLine ] of codeLines.entries()) {
-            const byLineIndex = lineNumber - 1 + lineIndex + codeLineIndex;
-            const inLine = byLine[byLineIndex];
-            const codeLineOffset = codeLineIndex ? 0 : column - 1 + tickCount;
-            let match = null;
-            while ((match = emphasisMarkersRe.exec(codeLine))) {
-              inLine.push(codeLineOffset + match.index);
-            }
-            byLine[byLineIndex] = inLine;
-          }
-        }
-      );
-    }
-  });
-  return byLine;
-}
-module.exports.emphasisMarkersInContent = emphasisMarkersInContent;
-
 /**
  * Returns an object with information about reference links and images.
  *
@@ -1092,3 +983,23 @@ function expandTildePath(file, os) {
   return homedir ? file.replace(/^~($|\/|\\)/, `${homedir}$1`) : file;
 }
 module.exports.expandTildePath = expandTildePath;
+
+// Copied from markdownlint.js to avoid TypeScript compiler import() issue.
+/**
+ * @typedef {Object} MarkdownItToken
+ * @property {string[][]} attrs HTML attributes.
+ * @property {boolean} block Block-level token.
+ * @property {MarkdownItToken[]} children Child nodes.
+ * @property {string} content Tag contents.
+ * @property {boolean} hidden Ignore element.
+ * @property {string} info Fence info.
+ * @property {number} level Nesting level.
+ * @property {number[]} map Beginning/ending line numbers.
+ * @property {string} markup Markup text.
+ * @property {Object} meta Arbitrary data.
+ * @property {number} nesting Level change.
+ * @property {string} tag HTML tag name.
+ * @property {string} type Token type.
+ * @property {number} lineNumber Line number (1-based).
+ * @property {string} line Line content.
+ */