markdownlint 0.30.0 → 0.31.0

package/doc/Rules.md

@@ -2216,6 +2216,10 @@ Tags: `images`, `links`
 
 Aliases: `reference-links-images`
 
+Parameters:
+
+- `shortcut_syntax`: Include shortcut syntax (`boolean`, default `false`)
+
 Links and images in Markdown can provide the link destination or image source
 at the time of use or can define it elsewhere and use a label for reference.
 The reference format is convenient for keeping paragraph text clutter-free
@@ -2236,13 +2240,16 @@ Shortcut: ![image]
 [image]: https://example.com/image
 ```
 
-A link or image renders correctly when a corresponding label is defined, but
-the text displays with brackets if the label is not present. This rule warns
-of undefined labels for "full" and "collapsed" reference syntax.
+A link or image renders correctly when the corresponding label is defined, but
+displays as text with brackets when the label is not present. By default, this
+rule warns of undefined labels for "full" and "collapsed" reference syntax but
+not for "shortcut" syntax because it is ambiguous.
 
-> "Shortcut" syntax is ambiguous and a missing label will not generate an
-  error. For example, `[shortcut]` could be a shortcut link or the text
-  "shortcut" in brackets.
+The text `[example]` could be a shortcut link or the text "example" in brackets,
+so "shortcut" syntax is ignored by default. To include "shortcut" syntax, set
+the `include_shortcut` parameter to `true`. Note that doing so produces warnings
+for *all* text in the document that *could* be a shortcut. If bracketed text is
+intentional, brackets can be escaped with the `\` character: `\[example\]`.
 
 <a name="md053"></a>
 

package/doc/md052.md

@@ -4,6 +4,10 @@ Tags: `images`, `links`
 
 Aliases: `reference-links-images`
 
+Parameters:
+
+- `shortcut_syntax`: Include shortcut syntax (`boolean`, default `false`)
+
 Links and images in Markdown can provide the link destination or image source
 at the time of use or can define it elsewhere and use a label for reference.
 The reference format is convenient for keeping paragraph text clutter-free
@@ -24,10 +28,13 @@ Shortcut: ![image]
 [image]: https://example.com/image
 ```
 
-A link or image renders correctly when a corresponding label is defined, but
-the text displays with brackets if the label is not present. This rule warns
-of undefined labels for "full" and "collapsed" reference syntax.
+A link or image renders correctly when the corresponding label is defined, but
+displays as text with brackets when the label is not present. By default, this
+rule warns of undefined labels for "full" and "collapsed" reference syntax but
+not for "shortcut" syntax because it is ambiguous.
 
-> "Shortcut" syntax is ambiguous and a missing label will not generate an
-  error. For example, `[shortcut]` could be a shortcut link or the text
-  "shortcut" in brackets.
+The text `[example]` could be a shortcut link or the text "example" in brackets,
+so "shortcut" syntax is ignored by default. To include "shortcut" syntax, set
+the `include_shortcut` parameter to `true`. Note that doing so produces warnings
+for *all* text in the document that *could* be a shortcut. If bracketed text is
+intentional, brackets can be escaped with the `\` character: `\[example\]`.

package/helpers/helpers.js

@@ -322,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) {
@@ -339,8 +345,17 @@ function filterTokens(params, type, handler) {
 }
 module.exports.filterTokens = filterTokens;
 
-// Get line metadata array
-module.exports.getLineMetadata = function getLineMetadata(params) {
+/**
+ * @typedef {Array} LineMetadata
+ */
+
+/**
+ * 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 ]
   );
@@ -372,18 +387,32 @@ module.exports.getLineMetadata = function getLineMetadata(params) {
     lineMetadata[token.map[0]][6] = 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).
+ * @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);
   }
 }
@@ -454,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) {
@@ -945,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.
+ */

package/helpers/micromark.cjs

@@ -10,6 +10,8 @@ const {
 } = require("markdownlint-micromark");
 const { newLineRe } = require("./shared.js");
 
+const flatTokensSymbol = Symbol("flat-tokens");
+
 /**
  * Markdown token.
  *
@@ -21,9 +23,32 @@ const { newLineRe } = require("./shared.js");
  * @property {number} endColumn End column (1-based).
  * @property {string} text Token text.
  * @property {Token[]} children Child tokens.
- * @property {Token[]} [htmlFlowChildren] Child tokens for htmlFlow.
  */
 
+/**
+ * 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("-") &&
+      !comment.includes("--")
+    );
+  }
+  return false;
+}
+
 /**
  * Parses a Markdown document and returns Micromark events.
  *
@@ -82,19 +107,21 @@ function micromarkParseWithOffset(
 
   // Create Token objects
   const document = [];
+  let flatTokens = [];
   let current = {
     "children": document
   };
   const history = [ current ];
   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") {
+    if ((kind === "enter") && !skipHtmlFlowChildren) {
       const previous = current;
       history.push(previous);
       current = {
@@ -106,7 +133,11 @@ function micromarkParseWithOffset(
         text,
         "children": []
       };
-      if (current.type === "htmlFlow") {
+      previous.children.push(current);
+      flatTokens.push(current);
+      // @ts-ignore
+      if ((current.type === "htmlFlow") && !isHtmlFlowComment(current)) {
+        skipHtmlFlowChildren = true;
         if (!reparseOptions || !lines) {
           reparseOptions = {
             ...micromarkOptions,
@@ -123,23 +154,32 @@ function micromarkParseWithOffset(
         const reparseMarkdown = lines
           .slice(current.startLine - 1, current.endLine)
           .join("\n");
-        current.htmlFlowChildren = micromarkParseWithOffset(
+        const tokens = micromarkParseWithOffset(
           reparseMarkdown,
           reparseOptions,
           referencesDefined,
           current.startLine - 1
         );
+        current.children = tokens;
+        // Avoid stack overflow of Array.push(...spread)
+        // eslint-disable-next-line unicorn/prefer-spread
+        flatTokens = flatTokens.concat(tokens[flatTokensSymbol]);
       }
-      previous.children.push(current);
     } else if (kind === "exit") {
-      Object.freeze(current.children);
-      Object.freeze(current);
-      // @ts-ignore
-      current = history.pop();
+      if (type === "htmlFlow") {
+        skipHtmlFlowChildren = false;
+      }
+      if (!skipHtmlFlowChildren) {
+        Object.freeze(current.children);
+        Object.freeze(current);
+        // @ts-ignore
+        current = history.pop();
+      }
     }
   }
 
   // Return document
+  Object.defineProperty(document, flatTokensSymbol, { "value": flatTokens });
   Object.freeze(document);
   return document;
 }
@@ -166,83 +206,73 @@ function micromarkParse(
 }
 
 /**
- * Filter a list of Micromark tokens by predicate.
- *
- * @param {Token[]} tokens Micromark tokens.
- * @param {Function} allowed Allowed token predicate.
- * @param {Function} [transformChildren] Transform children predicate.
- * @returns {Token[]} Filtered tokens.
+ * @callback AllowedPredicate
+ * @param {Token} token Micromark token.
+ * @returns {boolean} True iff allowed.
  */
-function filterByPredicate(tokens, allowed, transformChildren) {
-  const result = [];
-  const pending = [ ...tokens ];
-  let token = null;
-  while ((token = pending.shift())) {
-    if (allowed(token)) {
-      result.push(token);
-    }
-    if (token.children.length > 0) {
-      const transformed =
-        transformChildren ? transformChildren(token) : token.children;
-      pending.unshift(...transformed);
-    }
-  }
-  return result;
-}
 
 /**
- * Filter a list of Micromark tokens by type.
- *
- * @param {Token[]} tokens Micromark tokens.
- * @param {string[]} allowed Types to allow.
- * @returns {Token[]} Filtered tokens.
+ * @callback TransformPredicate
+ * @param {Token} token Micromark token.
+ * @returns {Token[]} Child tokens.
  */
-function filterByTypes(tokens, allowed) {
-  return filterByPredicate(
-    tokens,
-    (token) => allowed.includes(token.type)
-  );
-}
 
 /**
- * Filter a list of Micromark tokens for HTML 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 filterByHtmlTokens(tokens) {
+function filterByPredicate(tokens, allowed, transformChildren) {
   const result = [];
-  const pending = [ tokens ];
-  let current = null;
-  while ((current = pending.shift())) {
-    for (const token of filterByTypes(current, [ "htmlFlow", "htmlText" ])) {
-      if (token.type === "htmlText") {
+  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);
-      } else {
-        // token.type === "htmlFlow"
-        // @ts-ignore
-        pending.push(token.htmlFlowChildren);
       }
+      const { children } = token;
+      if (children.length > 0) {
+        const transformed =
+          transformChildren ? transformChildren(token) : children;
+        queue.push(
+          {
+            "array": transformed,
+            "index": 0
+          }
+        );
+      }
+    } else {
+      queue.pop();
     }
   }
   return result;
 }
 
 /**
- * Returns a list of all nested child tokens.
+ * Filter a list of Micromark tokens by type.
  *
- * @param {Token} parent Micromark token.
- * @returns {Token[]} Flattened children.
+ * @param {Token[]} tokens Micromark tokens.
+ * @param {string[]} allowed Types to allow.
+ * @returns {Token[]} Filtered tokens.
  */
-function flattenedChildren(parent) {
-  const result = [];
-  const pending = [ ...parent.children ];
-  let token = null;
-  while ((token = pending.shift())) {
-    result.push(token);
-    pending.unshift(...token.children);
+function filterByTypes(tokens, allowed) {
+  const predicate = (token) => allowed.includes(token.type);
+  const flatTokens = tokens[flatTokensSymbol];
+  if (flatTokens) {
+    return flatTokens.filter(predicate);
   }
-  return result;
+  return filterByPredicate(tokens, predicate);
 }
 
 /**
@@ -338,10 +368,8 @@ function tokenIfType(token, type) {
 
 module.exports = {
   "parse": micromarkParse,
-  filterByHtmlTokens,
   filterByPredicate,
   filterByTypes,
-  flattenedChildren,
   getHeadingLevel,
   getHtmlTagInfo,
   getMicromarkEvents,

package/helpers/package.json

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

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.30.0";
+module.exports.version = "0.31.0";

package/lib/markdownlint.d.ts

@@ -8,7 +8,7 @@ export = markdownlint;
  */
 declare function markdownlint(options: Options | null, callback: LintCallback): void;
 declare namespace markdownlint {
-    export { markdownlintSync as sync, readConfig, readConfigSync, getVersion, promises, RuleFunction, RuleParams, MarkdownItToken, RuleOnError, RuleOnErrorInfo, RuleOnErrorFixInfo, Rule, Options, Plugin, ToStringCallback, LintResults, LintError, FixInfo, LintCallback, Configuration, RuleConfiguration, ConfigurationParser, ReadConfigCallback, ResolveConfigExtendsCallback };
+    export { markdownlintSync as sync, readConfig, readConfigSync, getVersion, promises, RuleFunction, RuleParams, MarkdownItToken, RuleOnError, RuleOnErrorInfo, RuleOnErrorFixInfo, Rule, Options, Plugin, ToStringCallback, LintResults, LintError, FixInfo, LintContentCallback, LintCallback, Configuration, RuleConfiguration, ConfigurationParser, ReadConfigCallback, ResolveConfigExtendsCallback };
 }
 /**
  * Configuration options.
@@ -64,7 +64,7 @@ type Options = {
 /**
  * Called with the result of the lint function.
  */
-type LintCallback = (err: Error | null, results?: LintResults) => void;
+type LintCallback = (error: Error | null, results?: LintResults) => void;
 /**
  * Lint specified Markdown files synchronously.
  *
@@ -353,6 +353,10 @@ type FixInfo = {
      */
     insertText?: string;
 };
+/**
+ * Called with the result of linting a string or document.
+ */
+type LintContentCallback = (error: Error | null, result?: LintError[]) => void;
 /**
  * Configuration object for linting rules. For a detailed schema, see
  * {@link  ../schema/markdownlint-config-schema.json}.

package/lib/markdownlint.js

@@ -520,7 +520,7 @@ function getEnabledRulesPerLineNumber(
  * @param {boolean} handleRuleFailures Whether to handle exceptions in rules.
  * @param {boolean} noInlineConfig Whether to allow inline configuration.
  * @param {number} resultVersion Version of the LintResults object to return.
- * @param {Function} callback Callback (err, result) function.
+ * @param {LintContentCallback} callback Callback (err, result) function.
  * @returns {void}
  */
 function lintContent(
@@ -809,7 +809,7 @@ function lintContent(
  * @param {number} resultVersion Version of the LintResults object to return.
  * @param {Object} fs File system implementation.
  * @param {boolean} synchronous Whether to execute synchronously.
- * @param {Function} callback Callback (err, result) function.
+ * @param {LintContentCallback} callback Callback (err, result) function.
  * @returns {void}
  */
 function lintFile(
@@ -859,7 +859,7 @@ function lintFile(
  *
  * @param {Options | null} options Options object.
  * @param {boolean} synchronous Whether to execute synchronously.
- * @param {Function} callback Callback (err, result) function.
+ * @param {LintCallback} callback Callback (err, result) function.
  * @returns {void}
  */
 function lintInput(options, synchronous, callback) {
@@ -1022,7 +1022,7 @@ function markdownlintPromise(options) {
  * @returns {LintResults} Results object.
  */
 function markdownlintSync(options) {
-  let results = {};
+  let results = null;
   lintInput(options, true, function callback(error, res) {
     if (error) {
       throw error;
@@ -1176,6 +1176,7 @@ function readConfig(file, parsers, fs, callback) {
   }
   // Read file
   file = helpers.expandTildePath(file, require("node:os"));
+  // eslint-disable-next-line n/prefer-promises/fs
   fs.readFile(file, "utf8", (err, content) => {
     if (err) {
       // @ts-ignore
@@ -1416,12 +1417,21 @@ module.exports = markdownlint;
  * @property {string} [insertText] Text to insert (after deleting).
  */
 
+/**
+ * Called with the result of linting a string or document.
+ *
+ * @callback LintContentCallback
+ * @param {Error | null} error Error iff failed.
+ * @param {LintError[]} [result] Result iff successful.
+ * @returns {void}
+ */
+
 /**
  * Called with the result of the lint function.
  *
  * @callback LintCallback
- * @param {Error | null} err Error object or null.
- * @param {LintResults} [results] Lint results.
+ * @param {Error | null} error Error object iff failed.
+ * @param {LintResults} [results] Lint results iff succeeded.
  * @returns {void}
  */
 

package/lib/md032.js

@@ -4,8 +4,7 @@
 
 const { addErrorContext, blockquotePrefixRe, isBlankLine } =
   require("../helpers");
-const { filterByPredicate, flattenedChildren } =
-  require("../helpers/micromark.cjs");
+const { filterByPredicate } = require("../helpers/micromark.cjs");
 
 const nonContentTokens = new Set([
   "blockQuoteMarker",
@@ -47,7 +46,9 @@ module.exports = {
     const topLevelLists = filterByPredicate(
       parsers.micromark.tokens,
       isList,
-      (token) => (isList(token) ? [] : token.children)
+      (token) => (
+        (isList(token) || (token.type === "htmlFlow")) ? [] : token.children
+      )
     );
     for (const list of topLevelLists) {
 
@@ -59,7 +60,11 @@ module.exports = {
 
       // Find the "visual" end of the list
       let endLine = list.endLine;
-      for (const child of flattenedChildren(list).reverse()) {
+      const flattenedChildren = filterByPredicate(
+        list.children,
+        () => true
+      );
+      for (const child of flattenedChildren.reverse()) {
         if (!nonContentTokens.has(child.type)) {
           endLine = child.endLine;
           break;

package/lib/md033.js

@@ -3,7 +3,7 @@
 "use strict";
 
 const { addError } = require("../helpers");
-const { filterByHtmlTokens, getHtmlTagInfo } =
+const { filterByTypes, getHtmlTagInfo } =
   require("../helpers/micromark.cjs");
 
 const nextLinesRe = /[\r\n][\s\S]*$/;
@@ -16,7 +16,8 @@ module.exports = {
     let allowedElements = params.config.allowed_elements;
     allowedElements = Array.isArray(allowedElements) ? allowedElements : [];
     allowedElements = allowedElements.map((element) => element.toLowerCase());
-    for (const token of filterByHtmlTokens(params.parsers.micromark.tokens)) {
+    const { tokens } = params.parsers.micromark;
+    for (const token of filterByTypes(tokens, [ "htmlText" ])) {
       const htmlTagInfo = getHtmlTagInfo(token);
       if (
         htmlTagInfo &&