markdownlint 0.31.1 → 0.32.1

package/doc/md053.md

@@ -11,9 +11,9 @@ Parameters:
 Fixable: Some violations can be fixed by tooling
 
 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
-and makes it easy to reuse the same URL in multiple places.
+at the time of use or can use a label to reference a definition elsewhere in
+the document. The latter reference format is convenient for keeping paragraph
+text clutter-free and makes it easy to reuse the same URL in multiple places.
 
 Because link and image reference definitions are located separately from
 where they are used, there are two scenarios where a definition can be

package/doc/md054.md

@@ -0,0 +1,100 @@
+# `MD054` - Link and image style
+
+Tags: `images`, `links`
+
+Aliases: `link-image-style`
+
+Parameters:
+
+- `autolink`: Allow autolinks (`boolean`, default `true`)
+- `collapsed`: Allow collapsed reference links and images (`boolean`, default
+  `true`)
+- `full`: Allow full reference links and images (`boolean`, default `true`)
+- `inline`: Allow inline links and images (`boolean`, default `true`)
+- `shortcut`: Allow shortcut reference links and images (`boolean`, default
+  `true`)
+- `url_inline`: Allow URLs as inline links (`boolean`, default `true`)
+
+Fixable: Some violations can be fixed by tooling
+
+Links and images in Markdown can provide the link destination or image source at
+the time of use or can use a label to reference a definition elsewhere in the
+document. The three reference formats are convenient for keeping paragraph text
+clutter-free and make it easy to reuse the same URL in multiple places.
+
+By default, this rule allows all link/image styles.
+
+Setting the `autolink` parameter to `false` disables autolinks:
+
+```markdown
+<https://example.com>
+```
+
+Setting the `inline` parameter to `false` disables inline links and images:
+
+```markdown
+[link](https://example.com)
+
+![image](https://example.com)
+```
+
+Setting the `full` parameter to `false` disables full reference links and
+images:
+
+```markdown
+[link][url]
+
+![image][url]
+
+[url]: https://example.com
+```
+
+Setting the `collapsed` parameter to `false` disables collapsed reference links
+and images:
+
+```markdown
+[url][]
+
+![url][]
+
+[url]: https://example.com
+```
+
+Setting the `shortcut` parameter to `false` disables shortcut reference links
+and images:
+
+```markdown
+[url]
+
+![url]
+
+[url]: https://example.com
+```
+
+To fix violations of this rule, change the link or image to use an allowed
+style. This rule can automatically fix violations when a link or image can be
+converted to the `inline` style (preferred) or a link can be converted to the
+`autolink` style (which does not support images and must be an absolute URL).
+This rule does *not* fix scenarios that require converting a link or image to
+the `full`, `collapsed`, or `shortcut` reference styles because that involves
+naming the reference and determining where to insert it in the document.
+
+Setting the `url_inline` parameter to `false` prevents the use of inline links
+with the same absolute URL text/destination and no title because such links can
+be converted to autolinks:
+
+```markdown
+[https://example.com](https://example.com)
+```
+
+To fix `url_inline` violations, use the simpler autolink syntax instead:
+
+```markdown
+<https://example.com>
+```
+
+Rationale: Consistent formatting makes it easier to understand a document.
+Autolinks are concise, but appear as URLs which can be long and confusing.
+Inline links and images can include descriptive text, but take up more space in
+Markdown form. Reference links and images can be easier to read and manipulate
+in Markdown form, but require a separate link reference definition.

package/helpers/helpers.js

@@ -4,17 +4,17 @@
 
 const micromark = require("./micromark.cjs");
 
-const { newLineRe } = require("./shared.js");
+const { newLineRe, nextLinesRe } = require("./shared.js");
+
 module.exports.newLineRe = newLineRe;
+module.exports.nextLinesRe = nextLinesRe;
 
 // Regular expression for matching common front matter (YAML and TOML)
 module.exports.frontMatterRe =
-  // eslint-disable-next-line max-len
-  /((^---\s*$[\s\S]*?^---\s*)|(^\+\+\+\s*$[\s\S]*?^(\+\+\+|\.\.\.)\s*)|(^\{\s*$[\s\S]*?^\}\s*))(\r\n|\r|\n|$)/m;
+  /((^---\s*$[\s\S]+?^---\s*)|(^\+\+\+\s*$[\s\S]+?^(\+\+\+|\.\.\.)\s*)|(^\{\s*$[\s\S]+?^\}\s*))(\r\n|\r|\n|$)/m;
 
 // Regular expression for matching the start of inline disable/enable comments
 const inlineCommentStartRe =
-  // eslint-disable-next-line max-len
   /(<!--\s*markdownlint-(disable|enable|capture|restore|disable-file|enable-file|disable-line|disable-next-line|configure-file))(?:\s|-->)/gi;
 module.exports.inlineCommentStartRe = inlineCommentStartRe;
 
@@ -32,12 +32,10 @@ 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)
@@ -124,6 +122,16 @@ function cloneIfUrl(url) {
 }
 module.exports.cloneIfUrl = cloneIfUrl;
 
+/**
+ * Gets a Regular Expression for matching the specified HTML attribute.
+ *
+ * @param {string} name HTML attribute name.
+ * @returns {RegExp} Regular Expression for matching.
+ */
+module.exports.getHtmlAttributeRe = function getHtmlAttributeRe(name) {
+  return new RegExp(`\\s${name}\\s*=\\s*['"]?([^'"\\s>]*)`, "iu");
+};
+
 /**
  * Returns true iff the input line is blank (contains nothing, whitespace, or
  * comments (unclosed start/end comments allowed)).
@@ -736,7 +744,19 @@ function getReferenceLinkImageData(params) {
           if (definitions.has(reference)) {
             duplicateDefinitions.push([ reference, token.startLine - 1 ]);
           } else {
-            definitions.set(reference, token.startLine - 1);
+            let destinationString = null;
+            const parent =
+              micromark.getTokenParentOfType(token, [ "definition" ]);
+            if (parent) {
+              destinationString = micromark.getTokenTextByType(
+                micromark.filterByPredicate(parent.children),
+                "definitionDestinationString"
+              );
+            }
+            definitions.set(
+              reference,
+              [ token.startLine - 1, destinationString ]
+            );
           }
         }
         break;

package/helpers/micromark.cjs

@@ -23,6 +23,7 @@ const flatTokensSymbol = Symbol("flat-tokens");
  * @property {number} endColumn End column (1-based).
  * @property {string} text Token text.
  * @property {Token[]} children Child tokens.
+ * @property {Token | null} parent Parent token.
  */
 
 /**
@@ -42,8 +43,13 @@ function isHtmlFlowComment(token) {
     return (
       !comment.startsWith(">") &&
       !comment.startsWith("->") &&
-      !comment.endsWith("-") &&
-      !comment.includes("--")
+      !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;
@@ -92,13 +98,15 @@ function getMicromarkEvents(
  * @param {Object} 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.
  * @returns {Token[]} Micromark tokens (frozen).
  */
 function micromarkParseWithOffset(
   markdown,
   micromarkOptions,
   referencesDefined,
-  lineDelta
+  lineDelta,
+  ancestor
 ) {
   // Use micromark to parse document into Events
   const events = getMicromarkEvents(
@@ -108,10 +116,19 @@ function micromarkParseWithOffset(
   // Create Token objects
   const document = [];
   let flatTokens = [];
-  let current = {
-    "children": document
+  /** @type {Token} */
+  const root = {
+    "type": "ROOT",
+    "startLine": -1,
+    "startColumn": -1,
+    "endLine": -1,
+    "endColumn": -1,
+    "text": "ROOT",
+    "children": document,
+    "parent": null
   };
-  const history = [ current ];
+  const history = [ root ];
+  let current = root;
   let reparseOptions = null;
   let lines = null;
   let skipHtmlFlowChildren = false;
@@ -131,11 +148,11 @@ function micromarkParseWithOffset(
         "endLine": endLine + lineDelta,
         endColumn,
         text,
-        "children": []
+        "children": [],
+        "parent": ((previous === root) ? (ancestor || null) : previous)
       };
       previous.children.push(current);
       flatTokens.push(current);
-      // @ts-ignore
       if ((current.type === "htmlFlow") && !isHtmlFlowComment(current)) {
         skipHtmlFlowChildren = true;
         if (!reparseOptions || !lines) {
@@ -158,7 +175,8 @@ function micromarkParseWithOffset(
           reparseMarkdown,
           reparseOptions,
           referencesDefined,
-          current.startLine - 1
+          current.startLine - 1,
+          current
         );
         current.children = tokens;
         // Avoid stack overflow of Array.push(...spread)
@@ -221,11 +239,12 @@ function micromarkParse(
  * Filter a list of Micromark tokens by predicate.
  *
  * @param {Token[]} tokens Micromark tokens.
- * @param {AllowedPredicate} allowed Allowed token predicate.
+ * @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 = [
     {
@@ -263,11 +282,11 @@ function filterByPredicate(tokens, allowed, transformChildren) {
  * Filter a list of Micromark tokens by type.
  *
  * @param {Token[]} tokens Micromark tokens.
- * @param {string[]} allowed Types to allow.
+ * @param {string[]} types Types to allow.
  * @returns {Token[]} Filtered tokens.
  */
-function filterByTypes(tokens, allowed) {
-  const predicate = (token) => allowed.includes(token.type);
+function filterByTypes(tokens, types) {
+  const predicate = (token) => types.includes(token.type);
   const flatTokens = tokens[flatTokensSymbol];
   if (flatTokens) {
     return flatTokens.filter(predicate);
@@ -319,7 +338,23 @@ function getHtmlTagInfo(token) {
 }
 
 /**
- * Get the text of a single token from a list of Micromark tokens by type.
+ * Gets the nearest parent of the specified type for a Micromark token.
+ *
+ * @param {Token} token Micromark token.
+ * @param {string[]} types Types to allow.
+ * @returns {Token | null} Parent token.
+ */
+function getTokenParentOfType(token, types) {
+  /** @type {Token | null} */
+  let current = token;
+  while ((current = current.parent) && !types.includes(current.type)) {
+    // Empty
+  }
+  return current;
+}
+
+/**
+ * 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.
@@ -327,7 +362,17 @@ function getHtmlTagInfo(token) {
  */
 function getTokenTextByType(tokens, type) {
   const filtered = tokens.filter((token) => token.type === type);
-  return (filtered.length === 1) ? filtered[0].text : null;
+  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;
 }
 
 /**
@@ -373,7 +418,9 @@ module.exports = {
   getHeadingLevel,
   getHtmlTagInfo,
   getMicromarkEvents,
+  getTokenParentOfType,
   getTokenTextByType,
+  inHtmlFlow,
   matchAndGetTokensByType,
   tokenIfType
 };

package/helpers/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markdownlint-rule-helpers",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "A collection of markdownlint helper functions for custom rules",
   "main": "./helpers.js",
   "exports": "./helpers.js",
@@ -12,6 +12,7 @@
     "url": "git+https://github.com/DavidAnson/markdownlint.git"
   },
   "bugs": "https://github.com/DavidAnson/markdownlint/issues",
+  "funding": "https://github.com/sponsors/DavidAnson",
   "engines": {
     "node": ">=16"
   },

package/helpers/shared.js

@@ -5,3 +5,6 @@
 // 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;
+
+// Regular expression for matching next lines
+module.exports.nextLinesRe = /[\r\n][\s\S]*$/;