markdownlint 0.37.4 → 0.38.0

package/lib/md025.mjs

@@ -1,7 +1,7 @@
 // @ts-check
 
 import { addErrorContext, frontMatterHasTitle } from "../helpers/helpers.cjs";
-import { getHeadingLevel, getHeadingText } from "../helpers/micromark-helpers.cjs";
+import { getHeadingLevel, getHeadingText, isDocfxTab, isHtmlFlowComment, nonContentTokens } from "../helpers/micromark-helpers.cjs";
 import { filterByTypesCached } from "./cache.mjs";
 
 /** @type {import("markdownlint").Rule} */
@@ -12,24 +12,32 @@ export default {
   "parser": "micromark",
   "function": function MD025(params, onError) {
     const level = Number(params.config.level || 1);
-    const foundFrontMatterTitle =
-      frontMatterHasTitle(
-        params.frontMatterLines,
-        params.config.front_matter_title
-      );
-    let hasTopLevelHeading = false;
-    for (const heading of filterByTypesCached([ "atxHeading", "setextHeading" ])) {
-      const headingLevel = getHeadingLevel(heading);
-      if (headingLevel === level) {
-        if (hasTopLevelHeading || foundFrontMatterTitle) {
-          const headingText = getHeadingText(heading);
+    const { tokens } = params.parsers.micromark;
+    const matchingHeadings = filterByTypesCached([ "atxHeading", "setextHeading" ])
+      .filter((heading) => (level === getHeadingLevel(heading)) && !isDocfxTab(heading));
+    if (matchingHeadings.length > 0) {
+      const foundFrontMatterTitle =
+        frontMatterHasTitle(
+          params.frontMatterLines,
+          params.config.front_matter_title
+        );
+      // Front matter title counts as a top-level heading if present
+      let hasTopLevelHeading = foundFrontMatterTitle;
+      if (!hasTopLevelHeading) {
+        // Check if the first matching heading is a top-level heading
+        const previousTokens = tokens.slice(0, tokens.indexOf(matchingHeadings[0]));
+        hasTopLevelHeading = previousTokens.every(
+          (token) => nonContentTokens.has(token.type) || isHtmlFlowComment(token)
+        );
+      }
+      if (hasTopLevelHeading) {
+        // All other matching headings are violations
+        for (const heading of matchingHeadings.slice(foundFrontMatterTitle ? 0 : 1)) {
           addErrorContext(
             onError,
             heading.startLine,
-            headingText
+            getHeadingText(heading)
           );
-        } else if (heading.startLine === 1) {
-          hasTopLevelHeading = true;
         }
       }
     }

package/lib/md027.mjs

@@ -1,8 +1,12 @@
 // @ts-check
 
 import { addErrorContext } from "../helpers/helpers.cjs";
+import { getParentOfType } from "../helpers/micromark-helpers.cjs";
 import { filterByTypesCached } from "./cache.mjs";
 
+/** @type {import("../helpers/micromark-helpers.cjs").TokenType[]} */
+const listTypes = [ "listOrdered", "listUnordered" ];
+
 /** @type {import("markdownlint").Rule} */
 export default {
   "names": [ "MD027", "no-multiple-space-blockquote" ],
@@ -10,6 +14,8 @@ export default {
   "tags": [ "blockquote", "whitespace", "indentation" ],
   "parser": "micromark",
   "function": function MD027(params, onError) {
+    const listItems = params.config.list_items;
+    const includeListItems = (listItems === undefined) ? true : !!listItems;
     const { tokens } = params.parsers.micromark;
     for (const token of filterByTypesCached([ "linePrefix" ])) {
       const parent = token.parent;
@@ -17,7 +23,11 @@ export default {
       const siblings = parent?.children || tokens;
       if (
         !codeIndented &&
-        (siblings[siblings.indexOf(token) - 1]?.type === "blockQuotePrefix")
+        (siblings[siblings.indexOf(token) - 1]?.type === "blockQuotePrefix") &&
+        (includeListItems || (
+          !listTypes.includes(siblings[siblings.indexOf(token) + 1]?.type) &&
+          !getParentOfType(token, listTypes)
+        ))
       ) {
         const { startColumn, startLine, text } = token;
         const { length } = text;

package/lib/md036.mjs

@@ -11,6 +11,11 @@ const emphasisTypes = [
   [ "strong", "strongText" ]
 ];
 
+const isParagraphChildMeaningful = (token) => !(
+  (token.type === "htmlText") ||
+  ((token.type === "data") && (token.text.trim().length === 0))
+);
+
 /** @type {import("markdownlint").Rule} */
 export default {
   "names": [ "MD036", "no-emphasis-as-heading" ],
@@ -22,9 +27,14 @@ export default {
     punctuation = String((punctuation === undefined) ? allPunctuation : punctuation);
     const punctuationRe = new RegExp("[" + punctuation + "]$");
     const paragraphTokens =
-      filterByTypesCached([ "paragraph" ])
+      filterByTypesCached([ "paragraph" ], true)
         .filter((token) =>
-          (token.parent?.type === "content") && !token.parent?.parent && (token.children.length === 1)
+          (token.parent?.type === "content") &&
+          (
+            !token.parent?.parent ||
+            ((token.parent?.parent?.type === "htmlFlow") && !token.parent?.parent?.parent)
+          ) &&
+          (token.children.filter(isParagraphChildMeaningful).length === 1)
         );
     for (const emphasisType of emphasisTypes) {
       const textTokens = getDescendantsByType(paragraphTokens, emphasisType);

package/lib/md038.mjs

@@ -4,19 +4,6 @@ import { addErrorContext } from "../helpers/helpers.cjs";
 import { getDescendantsByType } from "../helpers/micromark-helpers.cjs";
 import { filterByTypesCached } from "./cache.mjs";
 
-const leftSpaceRe = /^\s(?:[^`]|$)/;
-const rightSpaceRe = /[^`]\s$/;
-const trimCodeText = (text, start, end) => {
-  text = text.replace(/^\s+$/, "");
-  if (start) {
-    text = text.replace(/^\s+?(\s`|\S)/, "$1");
-  }
-  if (end) {
-    text = text.replace(/(`\s|\S)\s+$/, "$1");
-  }
-  return text;
-};
-
 /** @type {import("markdownlint").Rule} */
 export default {
   "names": [ "MD038", "no-space-in-code" ],
@@ -26,65 +13,59 @@ export default {
   "function": function MD038(params, onError) {
     const codeTexts = filterByTypesCached([ "codeText" ]);
     for (const codeText of codeTexts) {
-      const sequences = getDescendantsByType(codeText, [ "codeTextSequence" ]);
-      const startSequence = sequences[0];
-      const endSequence = sequences[sequences.length - 1];
       const datas = getDescendantsByType(codeText, [ "codeTextData" ]);
-      const startData = datas[0];
-      const endData = datas[datas.length - 1];
-      if (startSequence && endSequence && startData && endData) {
-        const spaceLeft = leftSpaceRe.test(startData.text);
-        const spaceRight = rightSpaceRe.test(endData.text);
-        if (spaceLeft || spaceRight) {
-          let lineNumber = startSequence.startLine;
-          let range = undefined;
-          let fixInfo = undefined;
-          if (startSequence.startLine === endSequence.endLine) {
-            range = [
-              startSequence.startColumn,
-              endSequence.endColumn - startSequence.startColumn
-            ];
-            fixInfo = {
-              "editColumn": startSequence.endColumn,
-              "deleteCount": endSequence.startColumn - startSequence.endColumn,
-              "insertText": trimCodeText(startData.text, true, true)
-            };
-          } else if (spaceLeft && (startSequence.endLine === startData.startLine)) {
-            range = [
-              startSequence.startColumn,
-              startData.endColumn - startSequence.startColumn
-            ];
-            fixInfo = {
-              "editColumn": startSequence.endColumn,
-              "deleteCount": startData.endColumn - startData.startColumn,
-              "insertText": trimCodeText(startData.text, true, false)
-            };
-          } else if (spaceRight && (endData.text.trim().length > 0)) {
-            lineNumber = endSequence.endLine;
-            range = [
-              endData.startColumn,
-              endSequence.endColumn - endData.startColumn
-            ];
-            fixInfo = {
-              "editColumn": endData.startColumn,
-              "deleteCount": endData.endColumn - endData.startColumn,
-              "insertText": trimCodeText(endData.text, false, true)
-            };
-          }
-          if (range) {
-            const context = params
-              .lines[lineNumber - 1]
-              .substring(range[0] - 1, range[0] - 1 + range[1]);
-            addErrorContext(
-              onError,
-              lineNumber,
-              context,
-              spaceLeft,
-              spaceRight,
-              range,
-              fixInfo
-            );
-          }
+      if (datas.length > 0) {
+        const paddings = getDescendantsByType(codeText, [ "codeTextPadding" ]);
+        // Check for extra space at start of code
+        const startPadding = paddings[0];
+        const startData = datas[0];
+        const startMatch = /^(\s+)(\S)/.exec(startData.text) || [ null, "", "" ];
+        const startBacktick = (startMatch[2] === "`");
+        const startCount = startMatch[1].length - ((startBacktick && !startPadding) ? 1 : 0);
+        const startSpaces = startCount > 0;
+        // Check for extra space at end of code
+        const endPadding = paddings[paddings.length - 1];
+        const endData = datas[datas.length - 1];
+        const endMatch = /(\S)(\s+)$/.exec(endData.text) || [ null, "", "" ];
+        const endBacktick = (endMatch[1] === "`");
+        const endCount = endMatch[2].length - ((endBacktick && !endPadding) ? 1 : 0);
+        const endSpaces = endCount > 0;
+        // Check if safe to remove 1-space padding
+        const removePadding = startSpaces && endSpaces && startPadding && endPadding && !startBacktick && !endBacktick;
+        const context = codeText.text;
+        // If extra space at start, report violation
+        if (startSpaces) {
+          const startColumn = (removePadding ? startPadding : startData).startColumn;
+          const length = startCount + (removePadding ? startPadding.text.length : 0);
+          addErrorContext(
+            onError,
+            startData.startLine,
+            context,
+            true,
+            false,
+            [ startColumn, length ],
+            {
+              "editColumn": startColumn,
+              "deleteCount": length
+            }
+          );
+        }
+        // If extra space at end, report violation
+        if (endSpaces) {
+          const endColumn = (removePadding ? endPadding : endData).endColumn;
+          const length = endCount + (removePadding ? endPadding.text.length : 0);
+          addErrorContext(
+            onError,
+            endData.endLine,
+            context,
+            false,
+            true,
+            [ endColumn - length, length ],
+            {
+              "editColumn": endColumn - length,
+              "deleteCount": length
+            }
+          );
         }
       }
     }

package/lib/md041.mjs

@@ -3,6 +3,26 @@
 import { addErrorContext, frontMatterHasTitle } from "../helpers/helpers.cjs";
 import { filterByTypes, getHeadingLevel, getHtmlTagInfo, isHtmlFlowComment, nonContentTokens } from "../helpers/micromark-helpers.cjs";
 
+const headingTagNameRe = /^h[1-6]$/;
+
+/**
+ * Gets the HTML tag name of an htmlFlow token.
+ *
+ * @param {import("markdownlint").MicromarkToken} token Micromark Token.
+ * @returns {string | null} Tag name.
+ */
+function getHtmlFlowTagName(token) {
+  const { children, type } = token;
+  if (type === "htmlFlow") {
+    const htmlTexts = filterByTypes(children, [ "htmlText" ], true);
+    const tagInfo = (htmlTexts.length > 0) && getHtmlTagInfo(htmlTexts[0]);
+    if (tagInfo) {
+      return tagInfo.name.toLowerCase();
+    }
+  }
+  return null;
+}
+
 /** @type {import("markdownlint").Rule} */
 export default {
   "names": [ "MD041", "first-line-heading", "first-line-h1" ],
@@ -10,24 +30,42 @@ export default {
   "tags": [ "headings" ],
   "parser": "micromark",
   "function": function MD041(params, onError) {
+    const allowPreamble = !!params.config.allow_preamble;
     const level = Number(params.config.level || 1);
-    if (!frontMatterHasTitle(params.frontMatterLines, params.config.front_matter_title)) {
-      params.parsers.micromark.tokens
-        .filter((token) => !nonContentTokens.has(token.type) && !isHtmlFlowComment(token))
-        .every((token) => {
-          let isError = true;
-          if ((token.type === "atxHeading") || (token.type === "setextHeading")) {
-            isError = (getHeadingLevel(token) !== level);
-          } else if (token.type === "htmlFlow") {
-            const htmlTexts = filterByTypes(token.children, [ "htmlText" ], true);
-            const tagInfo = (htmlTexts.length > 0) && getHtmlTagInfo(htmlTexts[0]);
-            isError = !tagInfo || (tagInfo.name.toLowerCase() !== `h${level}`);
-          }
-          if (isError) {
-            addErrorContext(onError, token.startLine, params.lines[token.startLine - 1]);
+    const { tokens } = params.parsers.micromark;
+    if (
+      !frontMatterHasTitle(
+        params.frontMatterLines,
+        params.config.front_matter_title
+      )
+    ) {
+      let errorLineNumber = 0;
+      for (const token of tokens) {
+        const { startLine, type } = token;
+        if (!nonContentTokens.has(type) && !isHtmlFlowComment(token)) {
+          let tagName = null;
+          if ((type === "atxHeading") || (type === "setextHeading")) {
+            // First heading needs to have the expected level
+            if (getHeadingLevel(token) !== level) {
+              errorLineNumber = startLine;
+            }
+            break;
+          } else if ((tagName = getHtmlFlowTagName(token)) && headingTagNameRe.test(tagName)) {
+            // First HTML element needs to have an <h?> with the expected level
+            if (tagName !== `h${level}`) {
+              errorLineNumber = startLine;
+            }
+            break;
+          } else if (!allowPreamble) {
+            // First non-content needs to be a heading with the expected level
+            errorLineNumber = startLine;
+            break;
           }
-          return false;
-        });
+        }
+      }
+      if (errorLineNumber > 0) {
+        addErrorContext(onError, errorLineNumber, params.lines[errorLineNumber - 1]);
+      }
     }
   }
 };

package/lib/md043.mjs

@@ -38,6 +38,8 @@ export default {
           }
         } else if (expected === "+") {
           matchAny = true;
+        } else if (expected === "?") {
+          // Allow current, match next
         } else if (handleCase(expected) === handleCase(actual)) {
           matchAny = false;
         } else if (matchAny) {

package/lib/md045.mjs

@@ -5,6 +5,7 @@ import { getHtmlTagInfo, getDescendantsByType } from "../helpers/micromark-helpe
 import { filterByTypesCached } from "./cache.mjs";
 
 const altRe = getHtmlAttributeRe("alt");
+const ariaHiddenRe = getHtmlAttributeRe("aria-hidden");
 
 /** @type {import("markdownlint").Rule} */
 export default {
@@ -40,7 +41,8 @@ export default {
         htmlTagInfo &&
         !htmlTagInfo.close &&
         (htmlTagInfo.name.toLowerCase() === "img") &&
-        !altRe.test(text)
+        !altRe.test(text) &&
+        (ariaHiddenRe.exec(text)?.[1].toLowerCase() !== "true")
       ) {
         const range = [
           startColumn,

package/lib/md051.mjs

@@ -1,7 +1,7 @@
 // @ts-check
 
 import { addError, getHtmlAttributeRe } from "../helpers/helpers.cjs";
-import { filterByPredicate, filterByTypes, getHtmlTagInfo } from "../helpers/micromark-helpers.cjs";
+import { filterByPredicate, filterByTypes, getHtmlTagInfo, isDocfxTab } from "../helpers/micromark-helpers.cjs";
 import { filterByTypesCached } from "./cache.mjs";
 
 // Regular expression for identifying HTML anchor names
@@ -66,7 +66,10 @@ export default {
   "parser": "micromark",
   "function": function MD051(params, onError) {
     const ignoreCase = params.config.ignore_case || false;
-    const fragments = new Map();
+    const ignoredPattern = params.config.ignored_pattern || "";
+    const ignoredPatternRe = new RegExp(ignoredPattern || "^$");
+    /** @type {Map<string, number>} */
+    const fragments = new Map([ [ "#top", 0 ] ]);
 
     // Process headings
     const headingTexts = filterByTypesCached([ "atxHeadingText", "setextHeadingText" ]);
@@ -107,18 +110,23 @@ export default {
       [ "definition", "definitionDestinationString" ]
     ];
     for (const [ parentType, definitionType ] of parentChilds) {
-      const links = filterByTypesCached([ parentType ]);
+      const links = filterByTypesCached([ parentType ])
+        .filter(
+          (link) => !((link.parent?.type === "atxHeadingText") && isDocfxTab(link.parent.parent))
+        );
       for (const link of links) {
         const definitions = filterByTypes(link.children, [ definitionType ]);
         for (const definition of definitions) {
           const { endColumn, startColumn } = definition;
           const text = unescapeStringTokenText(definition);
-          const encodedText = `#${encodeURIComponent(text.slice(1))}`;
+          const textSliceOne = text.slice(1);
+          const encodedText = `#${encodeURIComponent(textSliceOne)}`;
           if (
             (text.length > 1) &&
             text.startsWith("#") &&
             !fragments.has(encodedText) &&
-            !lineFragmentRe.test(encodedText)
+            !lineFragmentRe.test(encodedText) &&
+            !ignoredPatternRe.test(textSliceOne)
           ) {
             let context = undefined;
             let range = undefined;

package/lib/md052.mjs

@@ -13,6 +13,7 @@ export default {
   "function": function MD052(params, onError) {
     const { config, lines } = params;
     const shortcutSyntax = config.shortcut_syntax || false;
+    const ignoredLabels = new Set(config.ignored_labels || [ "x" ]);
     const { definitions, references, shortcuts } = getReferenceLinkImageData();
     const entries = shortcutSyntax ?
       [ ...references.entries(), ...shortcuts.entries() ] :
@@ -20,7 +21,7 @@ export default {
     // Look for links/images that use an undefined link reference
     for (const reference of entries) {
       const [ label, datas ] = reference;
-      if (!definitions.has(label)) {
+      if (!definitions.has(label) && !ignoredLabels.has(label)) {
         for (const data of datas) {
           const [ lineIndex, index, length ] = data;
           // Context will be incomplete if reporting for a multi-line link

package/lib/md059.mjs

@@ -0,0 +1,71 @@
+// @ts-check
+
+import { addErrorContext } from "../helpers/helpers.cjs";
+import { getDescendantsByType } from "../helpers/micromark-helpers.cjs";
+import { filterByTypesCached } from "./cache.mjs";
+
+/** @typedef {import("markdownlint").MicromarkTokenType} MicromarkTokenType */
+/** @type {Set<MicromarkTokenType>} */
+const allowedChildrenTypes = new Set([
+  "codeText",
+  "htmlText"
+]);
+const defaultProhibitedTexts = [
+  "click here",
+  "here",
+  "link",
+  "more"
+];
+
+/**
+ * Normalizes a string by removing extra whitespaces and punctuation.
+ *
+ * @param {string} str String to normalize.
+ * @returns {string} Normalized string.
+ */
+function normalize(str) {
+  return str
+    .replace(/[\W_]+/g, " ")
+    .replace(/\s+/g, " ")
+    .toLowerCase()
+    .trim();
+}
+
+/** @type {import("markdownlint").Rule} */
+export default {
+  "names": [ "MD059", "descriptive-link-text" ],
+  "description": "Link text should be descriptive",
+  "tags": [ "accessibility", "links" ],
+  "parser": "micromark",
+  "function": function MD059(params, onError) {
+    const prohibitedTexts = new Set(
+      (params.config.prohibited_texts || defaultProhibitedTexts).map(normalize)
+    );
+    if (prohibitedTexts.size > 0) {
+      const links = filterByTypesCached([ "link" ]);
+      for (const link of links) {
+        const labelTexts = getDescendantsByType(link, [ "label", "labelText" ]);
+        for (const labelText of labelTexts) {
+          const { children, endColumn, endLine, parent, startColumn, startLine, text } = labelText;
+          if (
+            !children.some((child) => allowedChildrenTypes.has(child.type)) &&
+            prohibitedTexts.has(normalize(text))
+          ) {
+            const range = (startLine === endLine) ?
+              [ startColumn, endColumn - startColumn ] :
+              undefined;
+            addErrorContext(
+              onError,
+              startLine,
+              // @ts-ignore
+              parent.text,
+              undefined,
+              undefined,
+              range
+            );
+          }
+        }
+      }
+    }
+  }
+};

package/lib/micromark-parse.mjs

@@ -20,6 +20,17 @@ import { flatTokensSymbol, htmlFlowSymbol, newLineRe } from "../helpers/shared.c
 /** @typedef {import("markdownlint").MicromarkToken} MicromarkToken */
 /** @typedef {import("./micromark-types.d.mts")} */
 
+/**
+ * Gets the Markdown text for a Micromark token.
+ *
+ * @param {string} markdown Markdown content.
+ * @param {Token} token Micromark token.
+ * @returns {string} Token text.
+ */
+function getText(markdown, token) {
+  return markdown.slice(token.start.offset, token.end.offset);
+}
+
 /**
  * Parse options.
  *
@@ -126,7 +137,7 @@ export function getEvents(
         // Create artificial event list and replicate content
         const text = eventsToReplicate
           .filter((event) => event[0] === "enter")
-          .map((event) => tokenizeContext.sliceSerialize(event[1]))
+          .map((event) => getText(markdown, event[1]))
           .join("")
           .trim();
         if ((text.length > 0) && !text.includes("]")) {
@@ -221,11 +232,11 @@ function parseInternal(
   let lines = null;
   let skipHtmlFlowChildren = false;
   for (const event of events) {
-    const [ kind, token, context ] = event;
+    const [ kind, token ] = event;
     const { type, start, end } = token;
     const { "column": startColumn, "line": startLine } = start;
     const { "column": endColumn, "line": endLine } = end;
-    const text = context.sliceSerialize(token);
+    const text = getText(markdown, token);
     if ((kind === "enter") && !skipHtmlFlowChildren) {
       const previous = current;
       history.push(previous);

package/lib/parse-configuration.mjs

@@ -0,0 +1,46 @@
+// @ts-check
+
+/**
+ * Result of a call to parseConfiguration.
+ *
+ * @typedef {Object} ParseConfigurationResult
+ * @property {Object | null} config Configuration object if successful.
+ * @property {string | null} message Error message if an error occurred.
+ */
+
+/**
+ * Parse the content of a configuration file.
+ *
+ * @param {string} name Name of the configuration file.
+ * @param {string} content Configuration content.
+ * @param {import("./markdownlint.mjs").ConfigurationParser[]} [parsers] Parsing function(s).
+ * @returns {ParseConfigurationResult} Parse configuration result.
+ */
+export default function parseConfiguration(name, content, parsers) {
+  let config = null;
+  let message = null;
+  const errors = [];
+  let index = 0;
+  // Try each parser
+  const failed = (parsers || [ JSON.parse ]).every((parser) => {
+    try {
+      const result = parser(content);
+      config = (result && (typeof result === "object") && !Array.isArray(result)) ? result : {};
+      // Succeeded
+      return false;
+    } catch (error) {
+      errors.push(`Parser ${index++}: ${error.message}`);
+    }
+    // Failed, try the next parser
+    return true;
+  });
+  // Message if unable to parse
+  if (failed) {
+    errors.unshift(`Unable to parse '${name}'`);
+    message = errors.join("; ");
+  }
+  return {
+    config,
+    message
+  };
+}

package/lib/rules.mjs

@@ -53,6 +53,7 @@ import md054 from "./md054.mjs";
 import md055 from "./md055.mjs";
 import md056 from "./md056.mjs";
 import md058 from "./md058.mjs";
+import md059 from "./md059.mjs";
 
 const rules = [
   md001,
@@ -108,7 +109,8 @@ const rules = [
   md055,
   md056,
   // md057: See https://github.com/markdownlint/markdownlint
-  md058
+  md058,
+  md059
 ];
 for (const rule of rules) {
   const name = rule.names[0].toLowerCase();