markdownlint 0.24.0 → 0.25.0

package/doc/CustomRules.md

@@ -41,7 +41,8 @@ A rule is implemented as an `Object` with one optional and four required propert
 - `description` is a required `String` value that describes the rule in output messages.
 - `information` is an optional (absolute) `URL` of a link to more information about the rule.
 - `tags` is a required `Array` of `String` values that groups related rules for easier customization.
-- `function` is a required synchronous `Function` that implements the rule and is passed two parameters:
+- `asynchronous` is an optional `Boolean` value that indicates whether the rule returns a `Promise` and runs asynchronously.
+- `function` is a required `Function` that implements the rule and is passed two parameters:
   - `params` is an `Object` with properties that describe the content being analyzed:
     - `name` is a `String` that identifies the input file/string.
     - `tokens` is an `Array` of [`markdown-it` `Token` objects](https://markdown-it.github.io/markdown-it/#Token)
@@ -51,7 +52,7 @@ A rule is implemented as an `Object` with one optional and four required propert
     - `config` is an `Object` corresponding to the rule's entry in `options.config` (if present).
   - `onError` is a function that takes a single `Object` parameter with one required and four optional properties:
     - `lineNumber` is a required `Number` specifying the 1-based line number of the error.
-    - `details` is an optional `String` with information about what caused the error.
+    - `detail` is an optional `String` with information about what caused the error.
     - `context` is an optional `String` with relevant text surrounding the error location.
     - `range` is an optional `Array` with two `Number` values identifying the 1-based column and length of the error.
     - `fixInfo` is an optional `Object` with information about how to fix the error (all properties are optional, but
@@ -66,15 +67,25 @@ A rule is implemented as an `Object` with one optional and four required propert
 The collection of helper functions shared by the built-in rules is available for use by custom rules in the
 [markdownlint-rule-helpers package](https://www.npmjs.com/package/markdownlint-rule-helpers).
 
+### Asynchronous Rules
+
+If a rule needs to perform asynchronous operations (such as fetching a network resource), it can specify the value `true` for its `asynchronous` property.
+Asynchronous rules should return a `Promise` from their `function` implementation that is resolved when the rule completes.
+(The value passed to `resolve(...)` is ignored.)
+Linting violations from asynchronous rules are reported via the `onError` function just like for synchronous rules.
+
+**Note**: Asynchronous rules cannot be referenced in a synchronous calling context (i.e., `markdownlint.sync(...)`).
+Attempting to do so throws an exception.
+
 ## Examples
 
 - [Simple rules used by the project's test cases](../test/rules)
 - [Code for all `markdownlint` built-in rules](../lib)
 - [Package configuration for publishing to npm](../test/rules/npm)
   - Packages should export a single rule object or an `Array` of rule objects
-- [Custom rules from the Microsoft/vscode-docs-authoring repository](https://github.com/microsoft/vscode-docs-authoring/tree/master/packages/docs-linting/markdownlint-custom-rules)
+- [Custom rules from the Microsoft/vscode-docs-authoring repository](https://github.com/microsoft/vscode-docs-authoring/tree/main/packages/docs-linting/markdownlint-custom-rules)
 - [Custom rules from the axibase/docs-util repository](https://github.com/axibase/docs-util/tree/master/linting-rules)
-- [Custom rules from the webhintio/hint repository](https://github.com/webhintio/hint/blob/master/scripts/lint-markdown.js)
+- [Custom rules from the webhintio/hint repository](https://github.com/webhintio/hint/blob/main/scripts/lint-markdown.js)
 
 ## References
 

package/doc/Rules.md

@@ -292,7 +292,11 @@ Tags: bullet, ul, indentation
 
 Aliases: ul-indent
 
-Parameters: indent, start_indented (number; default 2, boolean; default false)
+<!-- markdownlint-disable line-length -->
+
+Parameters: indent, start_indented, start_indent (number; default 2, boolean; default false, number; defaults to indent)
+
+<!-- markdownlint-restore -->
 
 Fixable: Most violations can be fixed by tooling
 
@@ -319,7 +323,9 @@ rule).
 
 The `start_indented` parameter allows the first level of lists to be indented by
 the configured number of spaces rather than starting at zero (the inverse of
-MD006).
+MD006). The `start_indent` parameter allows the first level of lists to be indented
+by a different number of spaces than the rest (ignored when `start_indented` is not
+set).
 
 Rationale: Indenting by 2 spaces allows the content of a nested list to be in
 line with the start of the content of the parent list when a single space is
@@ -418,12 +424,14 @@ Some text
     * Spaces used to indent the list item instead
 ```
 
-You have the option to exclude this rule for code blocks. To do so, set the
-`code_blocks` parameter to `false`. Code blocks are included by default since
-handling of tabs by tools is often inconsistent (ex: using 4 vs. 8 spaces).
+You have the option to exclude this rule for code blocks and spans. To do so,
+set the `code_blocks` parameter to `false`. Code blocks and spans are included
+by default since handling of tabs by Markdown tools can be inconsistent (e.g.,
+using 4 vs. 8 spaces).
 
-If you would like the fixer to change tabs to x spaces, then configure the `spaces_per_tab`
-parameter to the number x. The default value would be 1.
+By default, violations of this rule are fixed by replacing the tab with 1 space
+character. To use a different number of spaces, set the `spaces_per_tab`
+parameter to the desired value.
 
 Rationale: Hard tabs are often rendered inconsistently by different editors and
 can be harder to work with than spaces.
@@ -1331,20 +1339,20 @@ For more information, see <https://www.example.com/>.
 ```
 
 Note: To use a bare URL without it being converted into a link, enclose it in
-a code block, otherwise in some markdown parsers it _will_ be converted:
+a code block, otherwise in some markdown parsers it *will* be converted:
 
 ```markdown
 `https://www.example.com`
 ```
 
-Note: The following scenario does _not_ trigger this rule to avoid conflicts
+Note: The following scenario does *not* trigger this rule to avoid conflicts
 with `MD011`/`no-reversed-links`:
 
 ```markdown
 [https://www.example.com]
 ```
 
-The use of quotes around a bare link will _not_ trigger this rule, either:
+The use of quotes around a bare link will *not* trigger this rule, either:
 
 ```markdown
 "https://www.example.com"
@@ -1362,8 +1370,8 @@ Tags: hr
 
 Aliases: hr-style
 
-Parameters: style ("consistent", "---", "***", or other string specifying the
-horizontal rule; default "consistent")
+Parameters: style ("consistent", "---", "***", "___", or other string specifying
+the horizontal rule; default "consistent")
 
 This rule is triggered when inconsistent styles of horizontal rules are used
 in the document:
@@ -1762,7 +1770,8 @@ the proper capitalization, specify the desired letter case in the `names` array:
 ]
 ```
 
-Set the `code_blocks` parameter to `false` to disable this rule for code blocks.
+Set the `code_blocks` parameter to `false` to disable this rule for code blocks
+and spans.
 
 Rationale: Incorrect capitalization of proper names is usually a mistake.
 
@@ -1911,3 +1920,67 @@ The configured list style can be a specific symbol to use (backtick, tilde), or
 can require that usage be consistent within the document.
 
 Rationale: Consistent formatting makes it easier to understand a document.
+
+<a name="md049"></a>
+
+## MD049 - Emphasis style should be consistent
+
+Tags: emphasis
+
+Aliases: emphasis-style
+
+Parameters: style ("consistent", "asterisk", "underscore"; default "consistent")
+
+Fixable: Most violations can be fixed by tooling
+
+This rule is triggered when the symbols used in the document for emphasis do not
+match the configured emphasis style:
+
+```markdown
+*Text*
+_Text_
+```
+
+To fix this issue, use the configured emphasis style throughout the document:
+
+```markdown
+*Text*
+*Text*
+```
+
+The configured emphasis style can be a specific symbol to use ("asterisk",
+"underscore"), or can require that usage be consistent within the document.
+
+Rationale: Consistent formatting makes it easier to understand a document.
+
+<a name="md050"></a>
+
+## MD050 - Strong style should be consistent
+
+Tags: emphasis
+
+Aliases: strong-style
+
+Parameters: style ("consistent", "asterisk", "underscore"; default "consistent")
+
+Fixable: Most violations can be fixed by tooling
+
+This rule is triggered when the symbols used in the document for strong do not
+match the configured strong style:
+
+```markdown
+**Text**
+__Text__
+```
+
+To fix this issue, use the configured strong style throughout the document:
+
+```markdown
+**Text**
+**Text**
+```
+
+The configured strong style can be a specific symbol to use ("asterisk",
+"underscore"), or can require that usage be consistent within the document.
+
+Rationale: Consistent formatting makes it easier to understand a document.

package/helpers/helpers.js

@@ -2,8 +2,6 @@
 
 "use strict";
 
-const os = require("os");
-
 // Regular expression for matching common newline characters
 // See NEWLINES_RE in markdown-it/lib/rules_core/normalize.js
 const newLineRe = /\r\n?|\n/g;
@@ -63,12 +61,20 @@ module.exports.isObject = function isObject(obj) {
 };
 
 // Returns true iff the input line is blank (no content)
-// Example: Contains nothing, whitespace, or comments
-const blankLineRe = />|(?:<!--.*?-->)/g;
+// Example: Contains nothing, whitespace, or comment (unclosed start/end okay)
 module.exports.isBlankLine = function isBlankLine(line) {
   // Call to String.replace follows best practices and is not a security check
   // False-positive for js/incomplete-multi-character-sanitization
-  return !line || !line.trim() || !line.replace(blankLineRe, "").trim();
+  return (
+    !line ||
+    !line.trim() ||
+    !line
+      .replace(/<!--.*?-->/g, "")
+      .replace(/<!--.*$/g, "")
+      .replace(/^.*-->/g, "")
+      .replace(/>/g, "")
+      .trim()
+  );
 };
 
 /**
@@ -181,6 +187,22 @@ module.exports.fencedCodeBlockStyleFor =
     }
   };
 
+/**
+ * Return the string representation of a emphasis or strong markup character.
+ *
+ * @param {string} markup Emphasis or strong string.
+ * @returns {string} String representation.
+ */
+module.exports.emphasisOrStrongStyleFor =
+  function emphasisOrStrongStyleFor(markup) {
+    switch (markup[0]) {
+      case "*":
+        return "asterisk";
+      default:
+        return "underscore";
+    }
+  };
+
 /**
  * Return the number of characters of indent for a token.
  *
@@ -247,11 +269,12 @@ module.exports.filterTokens = filterTokens;
  */
 function isMathBlock(token) {
   return (
-    (token.tag === "math") &&
+    ((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) {
@@ -293,14 +316,20 @@ module.exports.getLineMetadata = function getLineMetadata(params) {
   return lineMetadata;
 };
 
-// Calls the provided function for each line (with context)
-module.exports.forEachLine = function forEachLine(lineMetadata, handler) {
+/**
+ * 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).
+ * @returns {void}
+ */
+function forEachLine(lineMetadata, handler) {
   lineMetadata.forEach(function forMetadata(metadata) {
-    // Parameters:
-    // line, lineIndex, inCode, onFence, inTable, inItem, inBreak, inMath
     handler(...metadata);
   });
-};
+}
+module.exports.forEachLine = forEachLine;
 
 // Returns (nested) lists as a flat array (in order)
 module.exports.flattenLists = function flattenLists(tokens) {
@@ -311,10 +340,6 @@ module.exports.flattenLists = function flattenLists(tokens) {
   const nestingStack = [];
   let lastWithMap = { "map": [ 0, 1 ] };
   tokens.forEach((token) => {
-    if (isMathBlock(token) && token.map[1]) {
-      // markdown-it-texmath plugin does not account for math_block_end
-      token.map[1]++;
-    }
     if ((token.type === "bullet_list_open") ||
         (token.type === "ordered_list_open")) {
       // Save current context and start a new one
@@ -386,7 +411,8 @@ module.exports.forEachHeading = function forEachHeading(params, handler) {
  * Calls the provided function for each inline code span's content.
  *
  * @param {string} input Markdown content.
- * @param {Function} handler Callback function.
+ * @param {Function} handler Callback function taking (code, lineIndex,
+ * columnIndex, ticks).
  * @returns {void}
  */
 function forEachInlineCodeSpan(input, handler) {
@@ -521,26 +547,39 @@ module.exports.addErrorContext = function addErrorContext(
 };
 
 /**
- * Returns an array of code span ranges.
+ * Returns an array of code block and span content ranges.
  *
- * @param {string[]} lines Lines to scan for code span ranges.
- * @returns {number[][]} Array of ranges (line, index, length).
+ * @param {Object} params RuleParams instance.
+ * @param {Object} lineMetadata Line metadata object.
+ * @returns {number[][]} Array of ranges (lineIndex, columnIndex, length).
  */
-module.exports.inlineCodeSpanRanges = (lines) => {
+module.exports.codeBlockAndSpanRanges = (params, lineMetadata) => {
   const exclusions = [];
-  forEachInlineCodeSpan(
-    lines.join("\n"),
-    (code, lineIndex, columnIndex) => {
-      const codeLines = code.split(newLineRe);
-      // eslint-disable-next-line unicorn/no-for-loop
-      for (let i = 0; i < codeLines.length; i++) {
-        exclusions.push(
-          [ lineIndex + i, columnIndex, codeLines[i].length ]
-        );
-        columnIndex = 0;
-      }
+  // Add code block ranges (excludes fences)
+  forEachLine(lineMetadata, (line, lineIndex, inCode, onFence) => {
+    if (inCode && !onFence) {
+      exclusions.push([ lineIndex, 0, line.length ]);
     }
-  );
+  });
+  // Add code span ranges (excludes ticks)
+  filterTokens(params, "inline", (token) => {
+    if (token.children.some((child) => child.type === "code_inline")) {
+      const tokenLines = params.lines.slice(token.map[0], token.map[1]);
+      forEachInlineCodeSpan(
+        tokenLines.join("\n"),
+        (code, lineIndex, columnIndex) => {
+          const codeLines = code.split(newLineRe);
+          for (const [ i, line ] of codeLines.entries()) {
+            exclusions.push([
+              token.lineNumber - 1 + lineIndex + i,
+              i ? 0 : columnIndex,
+              line.length
+            ]);
+          }
+        }
+      );
+    }
+  });
   return exclusions;
 };
 
@@ -596,6 +635,18 @@ module.exports.frontMatterHasTitle =
 function emphasisMarkersInContent(params) {
   const { lines } = params;
   const byLine = new Array(lines.length);
+  // Search links
+  lines.forEach((tokenLine, tokenLineIndex) => {
+    const inLine = [];
+    let linkMatch = null;
+    while ((linkMatch = linkRe.exec(tokenLine))) {
+      let markerMatch = null;
+      while ((markerMatch = emphasisMarkersRe.exec(linkMatch[0]))) {
+        inLine.push(linkMatch.index + markerMatch.index);
+      }
+    }
+    byLine[tokenLineIndex] = inLine;
+  });
   // Search code spans
   filterTokens(params, "inline", (token) => {
     const { children, lineNumber, map } = token;
@@ -606,31 +657,19 @@ function emphasisMarkersInContent(params) {
         (code, lineIndex, column, tickCount) => {
           const codeLines = code.split(newLineRe);
           codeLines.forEach((codeLine, codeLineIndex) => {
+            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))) {
-              const byLineIndex = lineNumber - 1 + lineIndex + codeLineIndex;
-              const inLine = byLine[byLineIndex] || [];
-              const codeLineOffset = codeLineIndex ? 0 : column - 1 + tickCount;
               inLine.push(codeLineOffset + match.index);
-              byLine[byLineIndex] = inLine;
             }
+            byLine[byLineIndex] = inLine;
           });
         }
       );
     }
   });
-  // Search links
-  lines.forEach((tokenLine, tokenLineIndex) => {
-    let linkMatch = null;
-    while ((linkMatch = linkRe.exec(tokenLine))) {
-      let markerMatch = null;
-      while ((markerMatch = emphasisMarkersRe.exec(linkMatch[0]))) {
-        const inLine = byLine[tokenLineIndex] || [];
-        inLine.push(linkMatch.index + markerMatch.index);
-        byLine[tokenLineIndex] = inLine;
-      }
-    }
-  });
   return byLine;
 }
 module.exports.emphasisMarkersInContent = emphasisMarkersInContent;
@@ -639,9 +678,10 @@ module.exports.emphasisMarkersInContent = emphasisMarkersInContent;
  * Gets the most common line ending, falling back to the platform default.
  *
  * @param {string} input Markdown content to analyze.
+ * @param {string} [platform] Platform identifier (process.platform).
  * @returns {string} Preferred line ending.
  */
-function getPreferredLineEnding(input) {
+function getPreferredLineEnding(input, platform) {
   let cr = 0;
   let lf = 0;
   let crlf = 0;
@@ -662,7 +702,8 @@ function getPreferredLineEnding(input) {
   });
   let preferredLineEnding = null;
   if (!cr && !lf && !crlf) {
-    preferredLineEnding = os.EOL;
+    preferredLineEnding =
+      ((platform || process.platform) === "win32") ? "\r\n" : "\n";
   } else if ((lf >= crlf) && (lf >= cr)) {
     preferredLineEnding = "\n";
   } else if (crlf >= cr) {
@@ -777,3 +818,80 @@ module.exports.applyFixes = function applyFixes(input, errors) {
   // Return corrected input
   return lines.filter((line) => line !== null).join(lineEnding);
 };
+
+/**
+ * Gets the range and fixInfo values for reporting an error if the expected
+ * text is found on the specified line.
+ *
+ * @param {string[]} lines Lines of Markdown content.
+ * @param {number} lineIndex Line index to check.
+ * @param {string} search Text to search for.
+ * @param {string} replace Text to replace with.
+ * @returns {Object} Range and fixInfo wrapper.
+ */
+function getRangeAndFixInfoIfFound(lines, lineIndex, search, replace) {
+  let range = null;
+  let fixInfo = null;
+  const searchIndex = lines[lineIndex].indexOf(search);
+  if (searchIndex !== -1) {
+    const column = searchIndex + 1;
+    const length = search.length;
+    range = [ column, length ];
+    fixInfo = {
+      "editColumn": column,
+      "deleteCount": length,
+      "insertText": replace
+    };
+  }
+  return {
+    range,
+    fixInfo
+  };
+}
+module.exports.getRangeAndFixInfoIfFound = getRangeAndFixInfoIfFound;
+
+/**
+ * Gets the next (subsequent) child token if it is of the expected type.
+ *
+ * @param {Object} parentToken Parent token.
+ * @param {Object} childToken Child token basis.
+ * @param {string} nextType Token type of next token.
+ * @param {string} nextNextType Token type of next-next token.
+ * @returns {Object} Next token.
+ */
+function getNextChildToken(parentToken, childToken, nextType, nextNextType) {
+  const { children } = parentToken;
+  const index = children.indexOf(childToken);
+  if (
+    (index !== -1) &&
+    (children.length > index + 2) &&
+    (children[index + 1].type === nextType) &&
+    (children[index + 2].type === nextNextType)
+  ) {
+    return children[index + 1];
+  }
+  return null;
+}
+module.exports.getNextChildToken = getNextChildToken;
+
+/**
+ * Calls Object.freeze() on an object and its children.
+ *
+ * @param {Object} obj Object to deep freeze.
+ * @returns {Object} Object passed to the function.
+ */
+function deepFreeze(obj) {
+  const pending = [ obj ];
+  let current = null;
+  while ((current = pending.shift())) {
+    Object.freeze(current);
+    for (const name of Object.getOwnPropertyNames(current)) {
+      const value = current[name];
+      if (value && (typeof value === "object")) {
+        pending.push(value);
+      }
+    }
+  }
+  return obj;
+}
+module.exports.deepFreeze = deepFreeze;

package/helpers/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markdownlint-rule-helpers",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "A collection of markdownlint helper functions for custom rules",
   "main": "helpers.js",
   "author": "David Anson (https://dlaa.me/)",

package/lib/cache.js

@@ -2,20 +2,20 @@
 
 "use strict";
 
-let flattenedLists = null;
-module.exports.flattenedLists = (value) => {
+let codeBlockAndSpanRanges = null;
+module.exports.codeBlockAndSpanRanges = (value) => {
   if (value) {
-    flattenedLists = value;
+    codeBlockAndSpanRanges = value;
   }
-  return flattenedLists;
+  return codeBlockAndSpanRanges;
 };
 
-let inlineCodeSpanRanges = null;
-module.exports.inlineCodeSpanRanges = (value) => {
+let flattenedLists = null;
+module.exports.flattenedLists = (value) => {
   if (value) {
-    inlineCodeSpanRanges = value;
+    flattenedLists = value;
   }
-  return inlineCodeSpanRanges;
+  return flattenedLists;
 };
 
 let lineMetadata = null;
@@ -27,7 +27,7 @@ module.exports.lineMetadata = (value) => {
 };
 
 module.exports.clear = () => {
+  codeBlockAndSpanRanges = null;
   flattenedLists = null;
-  inlineCodeSpanRanges = null;
   lineMetadata = null;
 };

package/lib/constants.js

@@ -0,0 +1,7 @@
+// @ts-check
+
+"use strict";
+
+module.exports.deprecatedRuleNames = [ "MD002", "MD006" ];
+module.exports.homepage = "https://github.com/DavidAnson/markdownlint";
+module.exports.version = "0.25.0";

package/lib/markdownlint.d.ts

@@ -206,9 +206,9 @@ type RuleOnErrorInfo = {
      */
     lineNumber: number;
     /**
-     * Details about the error.
+     * Detail about the error.
      */
-    details?: string;
+    detail?: string;
     /**
      * Context for the error.
      */
@@ -263,6 +263,10 @@ type Rule = {
      * Rule tag(s).
      */
     tags: string[];
+    /**
+     * True if asynchronous.
+     */
+    asynchronous?: boolean;
     /**
      * Rule implementation.
      */