markdownlint 0.23.1 → 0.24.0

package/doc/Prettier.md

@@ -0,0 +1,23 @@
+# Using markdownlint with Prettier
+
+[`Prettier`](https://prettier.io) is a popular code formatter. For the most part,
+it works seamlessly with `markdownlint`. Special situations are documented
+below.
+
+## List item indentation
+
+The default settings of `markdownlint` and `Prettier` are compatible and don't
+result in any linting violations. If `Prettier` is used with `--tab-width` set
+to `4`, the following `markdownlint` configuration can be used:
+
+```json
+{
+  "MD007": {
+    "indent": 4
+  },
+  "MD030": {
+    "ul_single": 3,
+    "ul_multi": 3
+  }
+}
+```

package/doc/Rules.md

@@ -329,6 +329,8 @@ issue for multi-markdown parsers, which require 4-space indents. More informatio
 <https://cirosantilli.com/markdown-style-guide#indentation-of-content-inside-lists>
 and <http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting>.
 
+Note: See [Prettier.md](Prettier.md) for compatibility information.
+
 <a name="md009"></a>
 
 ## MD009 - Trailing spaces
@@ -388,7 +390,7 @@ Tags: whitespace, hard_tab
 
 Aliases: no-hard-tabs
 
-Parameters: code_blocks (boolean; default true)
+Parameters: code_blocks, spaces_per_tab (boolean; default true, number; default 1)
 
 Fixable: Most violations can be fixed by tooling
 
@@ -420,6 +422,9 @@ 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).
 
+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.
+
 Rationale: Hard tabs are often rendered inconsistently by different editors and
 can be harder to work with than spaces.
 
@@ -1180,6 +1185,8 @@ for your selected document style.
 
 Rationale: Violations of this rule can lead to improperly rendered content.
 
+Note: See [Prettier.md](Prettier.md) for compatibility information.
+
 <a name="md031"></a>
 
 ## MD031 - Fenced code blocks should be surrounded by blank lines
@@ -1569,6 +1576,14 @@ echo Hello world
 ```
 ````
 
+To display a code block without syntax highlighting, use:
+
+````markdown
+```text
+Plain text in a code block
+```
+````
+
 Rationale: Specifying a language improves content rendering by using the
 correct syntax highlighting for code. More information:
 <https://cirosantilli.com/markdown-style-guide#option-code-fenced>.

package/helpers/helpers.js

@@ -29,10 +29,11 @@ module.exports.orderedListItemMarkerRe = /^[\s>]*0*(\d+)[.)]/;
 const emphasisMarkersRe = /[_*]/g;
 
 // Regular expression for inline links and shortcut reference links
-const linkRe = /\[(?:[^[\]]|\[[^\]]*\])*\](?:\(\S*\))?/g;
+const linkRe = /(\[(?:[^[\]]|\[[^\]]*\])*\])(\(\S*\)|\[\S*\])?/g;
+module.exports.linkRe = linkRe;
 
-// readFile options for reading with the UTF-8 encoding
-module.exports.utf8Encoding = "utf8";
+// Regular expression for link reference definition lines
+module.exports.linkReferenceRe = /^ {0,3}\[[^\]]+]:\s.*$/;
 
 // All punctuation characters (normal and full-width)
 const allPunctuation = ".,;:!?。，；：！？";
@@ -302,14 +303,14 @@ module.exports.forEachLine = function forEachLine(lineMetadata, handler) {
 };
 
 // Returns (nested) lists as a flat array (in order)
-module.exports.flattenLists = function flattenLists(params) {
+module.exports.flattenLists = function flattenLists(tokens) {
   const flattenedLists = [];
   const stack = [];
   let current = null;
   let nesting = 0;
   const nestingStack = [];
   let lastWithMap = { "map": [ 0, 1 ] };
-  params.tokens.forEach((token) => {
+  tokens.forEach((token) => {
     if (isMathBlock(token) && token.map[1]) {
       // markdown-it-texmath plugin does not account for math_block_end
       token.map[1]++;
@@ -519,6 +520,47 @@ module.exports.addErrorContext = function addErrorContext(
   addError(onError, lineNumber, null, context, range, fixInfo);
 };
 
+/**
+ * Returns an array of code span ranges.
+ *
+ * @param {string[]} lines Lines to scan for code span ranges.
+ * @returns {number[][]} Array of ranges (line, index, length).
+ */
+module.exports.inlineCodeSpanRanges = (lines) => {
+  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;
+      }
+    }
+  );
+  return exclusions;
+};
+
+/**
+ * Determines whether the specified range overlaps another range.
+ *
+ * @param {number[][]} ranges Array of ranges (line, index, length).
+ * @param {number} lineIndex Line index to check.
+ * @param {number} index Index to check.
+ * @param {number} length Length to check.
+ * @returns {boolean} True iff the specified range overlaps.
+ */
+module.exports.overlapsAnyRange = (ranges, lineIndex, index, length) => (
+  !ranges.every((span) => (
+    (lineIndex !== span[0]) ||
+    (index + length < span[1]) ||
+    (index > span[1] + span[2])
+  ))
+);
+
 // Returns a range object for a line by applying a RegExp
 module.exports.rangeFromRegExp = function rangeFromRegExp(line, regexp) {
   let range = null;

package/helpers/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markdownlint-rule-helpers",
-  "version": "0.14.0",
+  "version": "0.15.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,14 +2,6 @@
 
 "use strict";
 
-let lineMetadata = null;
-module.exports.lineMetadata = (value) => {
-  if (value) {
-    lineMetadata = value;
-  }
-  return lineMetadata;
-};
-
 let flattenedLists = null;
 module.exports.flattenedLists = (value) => {
   if (value) {
@@ -18,7 +10,24 @@ module.exports.flattenedLists = (value) => {
   return flattenedLists;
 };
 
+let inlineCodeSpanRanges = null;
+module.exports.inlineCodeSpanRanges = (value) => {
+  if (value) {
+    inlineCodeSpanRanges = value;
+  }
+  return inlineCodeSpanRanges;
+};
+
+let lineMetadata = null;
+module.exports.lineMetadata = (value) => {
+  if (value) {
+    lineMetadata = value;
+  }
+  return lineMetadata;
+};
+
 module.exports.clear = () => {
-  lineMetadata = null;
   flattenedLists = null;
+  inlineCodeSpanRanges = null;
+  lineMetadata = null;
 };

package/lib/markdownlint.d.ts

@@ -8,7 +8,7 @@ export = markdownlint;
  */
 declare function markdownlint(options: Options, 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 };
+    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 };
 }
 /**
  * Configuration options.
@@ -52,9 +52,13 @@ type Options = {
      * Additional plugins.
      */
     markdownItPlugins?: Plugin[];
+    /**
+     * File system implementation.
+     */
+    fs?: any;
 };
 /**
- * Called with the result of the lint operation.
+ * Called with the result of the lint function.
  */
 type LintCallback = (err: Error | null, results?: LintResults) => void;
 /**
@@ -70,18 +74,21 @@ declare function markdownlintSync(options: Options): LintResults;
  * @param {string} file Configuration file name.
  * @param {ConfigurationParser[] | ReadConfigCallback} parsers Parsing
  * function(s).
+ * @param {Object} [fs] File system implementation.
  * @param {ReadConfigCallback} [callback] Callback (err, result) function.
  * @returns {void}
  */
-declare function readConfig(file: string, parsers: ConfigurationParser[] | ReadConfigCallback, callback?: ReadConfigCallback): void;
+declare function readConfig(file: string, parsers: ConfigurationParser[] | ReadConfigCallback, fs?: any, callback?: ReadConfigCallback): void;
 /**
  * Read specified configuration file synchronously.
  *
  * @param {string} file Configuration file name.
  * @param {ConfigurationParser[]} [parsers] Parsing function(s).
+ * @param {Object} [fs] File system implementation.
  * @returns {Configuration} Configuration object.
+ * @throws An Error if processing fails.
  */
-declare function readConfigSync(file: string, parsers?: ConfigurationParser[]): Configuration;
+declare function readConfigSync(file: string, parsers?: ConfigurationParser[], fs?: any): Configuration;
 /**
  * Gets the (semantic) version of the library.
  *
@@ -316,6 +323,10 @@ type LintError = {
  * Fix information.
  */
 type FixInfo = {
+    /**
+     * Line number (1-based).
+     */
+    lineNumber?: number;
     /**
      * Column of the fix (1-based).
      */
@@ -334,20 +345,24 @@ type FixInfo = {
  * {@link ../schema/markdownlint-config-schema.json}.
  */
 type Configuration = {
-    [x: string]: any;
+    [x: string]: RuleConfiguration;
 };
 /**
  * Rule configuration.
  */
-type RuleConfiguration = any;
+type RuleConfiguration = boolean | any;
 /**
  * Parses a configuration string and returns a configuration object.
  */
 type ConfigurationParser = (text: string) => Configuration;
 /**
- * Called with the result of the readConfig operation.
+ * Called with the result of the readConfig function.
  */
 type ReadConfigCallback = (err: Error | null, config?: Configuration) => void;
+/**
+ * Called with the result of the resolveConfigExtends function.
+ */
+type ResolveConfigExtendsCallback = (err: Error | null, path?: string) => void;
 /**
  * Lint specified Markdown files.
  *
@@ -360,6 +375,7 @@ declare function markdownlintPromise(options: Options): Promise<LintResults>;
  *
  * @param {string} file Configuration file name.
  * @param {ConfigurationParser[]} [parsers] Parsing function(s).
+ * @param {Object} [fs] File system implementation.
  * @returns {Promise<Configuration>} Configuration object.
  */
-declare function readConfigPromise(file: string, parsers?: ConfigurationParser[]): Promise<Configuration>;
+declare function readConfigPromise(file: string, parsers?: ConfigurationParser[], fs?: any): Promise<Configuration>;

package/lib/markdownlint.js

@@ -2,7 +2,6 @@
 
 "use strict";
 
-const fs = require("fs");
 const path = require("path");
 const { promisify } = require("util");
 const markdownIt = require("markdown-it");
@@ -190,7 +189,7 @@ function annotateTokens(tokens, lines) {
       (token.type === "thead_open") ||
       (token.type === "tbody_open")
     ) {
-      tableMap = token.map.slice();
+      tableMap = [ ...token.map ];
     } else if (
       (token.type === "tr_close") &&
       tableMap
@@ -203,7 +202,7 @@ function annotateTokens(tokens, lines) {
       tableMap = null;
     }
     if (tableMap && !token.map) {
-      token.map = tableMap.slice();
+      token.map = [ ...tableMap ];
     }
     // Update token metadata
     if (token.map) {
@@ -516,7 +515,8 @@ function lintContent(
     frontMatterLines
   };
   cache.lineMetadata(helpers.getLineMetadata(params));
-  cache.flattenedLists(helpers.flattenLists(params));
+  cache.flattenedLists(helpers.flattenLists(params.tokens));
+  cache.inlineCodeSpanRanges(helpers.inlineCodeSpanRanges(params.lines));
   // Function to run for each rule
   const result = (resultVersion === 0) ? {} : [];
   // eslint-disable-next-line jsdoc/require-jsdoc
@@ -684,6 +684,7 @@ function lintContent(
  * @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 {Object} fs File system implementation.
  * @param {boolean} synchronous Whether to execute synchronously.
  * @param {Function} callback Callback (err, result) function.
  * @returns {void}
@@ -697,6 +698,7 @@ function lintFile(
   handleRuleFailures,
   noInlineConfig,
   resultVersion,
+  fs,
   synchronous,
   callback) {
   // eslint-disable-next-line jsdoc/require-jsdoc
@@ -709,10 +711,9 @@ function lintFile(
   }
   // Make a/synchronous call to read file
   if (synchronous) {
-    // @ts-ignore
-    lintContentWrapper(null, fs.readFileSync(file, helpers.utf8Encoding));
+    lintContentWrapper(null, fs.readFileSync(file, "utf8"));
   } else {
-    fs.readFile(file, helpers.utf8Encoding, lintContentWrapper);
+    fs.readFile(file, "utf8", lintContentWrapper);
   }
 }
 
@@ -736,7 +737,7 @@ function lintInput(options, synchronous, callback) {
   }
   let files = [];
   if (Array.isArray(options.files)) {
-    files = options.files.slice();
+    files = [ ...options.files ];
   } else if (options.files) {
     files = [ String(options.files) ];
   }
@@ -755,6 +756,7 @@ function lintInput(options, synchronous, callback) {
     // @ts-ignore
     md.use(...plugin);
   });
+  const fs = options.fs || require("fs");
   const results = newResults(ruleList);
   let done = false;
   // Linting of strings is always synchronous
@@ -794,6 +796,7 @@ function lintInput(options, synchronous, callback) {
         handleRuleFailures,
         noInlineConfig,
         resultVersion,
+        fs,
         synchronous,
         syncCallback
       );
@@ -818,6 +821,7 @@ function lintInput(options, synchronous, callback) {
         handleRuleFailures,
         noInlineConfig,
         resultVersion,
+        fs,
         synchronous,
         (err, result) => {
           concurrency--;
@@ -928,17 +932,47 @@ function parseConfiguration(name, content, parsers) {
  *
  * @param {string} configFile Configuration file name.
  * @param {string} referenceId Referenced identifier to resolve.
+ * @param {Object} fs File system implementation.
+ * @param {ResolveConfigExtendsCallback} [callback] Callback (err, result)
+ * function.
+ * @returns {void}
+ */
+function resolveConfigExtends(configFile, referenceId, fs, callback) {
+  const configFileDirname = path.dirname(configFile);
+  const resolvedExtendsFile = path.resolve(configFileDirname, referenceId);
+  fs.access(resolvedExtendsFile, (err) => {
+    if (err) {
+      // Not a file, try require.resolve
+      try {
+        return callback(null, dynamicRequire.resolve(
+          referenceId,
+          { "paths": [ configFileDirname ] }
+        ));
+      } catch {
+        // Unable to resolve, use resolvedExtendsFile
+      }
+    }
+    return callback(null, resolvedExtendsFile);
+  });
+}
+
+/**
+ * Resolve referenced "extends" path in a configuration file
+ * using path.resolve() with require.resolve() as a fallback.
+ *
+ * @param {string} configFile Configuration file name.
+ * @param {string} referenceId Referenced identifier to resolve.
+ * @param {Object} fs File system implementation.
  * @returns {string} Resolved path to file.
  */
-function resolveConfigExtends(configFile, referenceId) {
+function resolveConfigExtendsSync(configFile, referenceId, fs) {
   const configFileDirname = path.dirname(configFile);
   const resolvedExtendsFile = path.resolve(configFileDirname, referenceId);
   try {
-    if (fs.statSync(resolvedExtendsFile).isFile()) {
-      return resolvedExtendsFile;
-    }
+    fs.accessSync(resolvedExtendsFile);
+    return resolvedExtendsFile;
   } catch {
-    // If not a file or fs.statSync throws, try require.resolve
+    // Not a file, try require.resolve
   }
   try {
     return dynamicRequire.resolve(
@@ -946,7 +980,7 @@ function resolveConfigExtends(configFile, referenceId) {
       { "paths": [ configFileDirname ] }
     );
   } catch {
-    // If require.resolve throws, return resolvedExtendsFile
+    // Unable to resolve, return resolvedExtendsFile
   }
   return resolvedExtendsFile;
 }
@@ -957,17 +991,26 @@ function resolveConfigExtends(configFile, referenceId) {
  * @param {string} file Configuration file name.
  * @param {ConfigurationParser[] | ReadConfigCallback} parsers Parsing
  * function(s).
+ * @param {Object} [fs] File system implementation.
  * @param {ReadConfigCallback} [callback] Callback (err, result) function.
  * @returns {void}
  */
-function readConfig(file, parsers, callback) {
+function readConfig(file, parsers, fs, callback) {
   if (!callback) {
-    // @ts-ignore
-    callback = parsers;
-    parsers = null;
+    if (fs) {
+      callback = fs;
+      fs = null;
+    } else {
+      // @ts-ignore
+      callback = parsers;
+      parsers = null;
+    }
+  }
+  if (!fs) {
+    fs = require("fs");
   }
   // Read file
-  fs.readFile(file, helpers.utf8Encoding, (err, content) => {
+  fs.readFile(file, "utf8", (err, content) => {
     if (err) {
       return callback(err);
     }
@@ -981,16 +1024,25 @@ function readConfig(file, parsers, callback) {
     const configExtends = config.extends;
     if (configExtends) {
       delete config.extends;
-      const resolvedExtends = resolveConfigExtends(file, configExtends);
-      return readConfig(resolvedExtends, parsers, (errr, extendsConfig) => {
-        if (errr) {
-          return callback(errr);
-        }
-        return callback(null, {
-          ...extendsConfig,
-          ...config
-        });
-      });
+      return resolveConfigExtends(
+        file,
+        configExtends,
+        fs,
+        (_, resolvedExtends) => readConfig(
+          resolvedExtends,
+          parsers,
+          fs,
+          (errr, extendsConfig) => {
+            if (errr) {
+              return callback(errr);
+            }
+            return callback(null, {
+              ...extendsConfig,
+              ...config
+            });
+          }
+        )
+      );
     }
     return callback(null, config);
   });
@@ -1003,11 +1055,12 @@ const readConfigPromisify = promisify && promisify(readConfig);
  *
  * @param {string} file Configuration file name.
  * @param {ConfigurationParser[]} [parsers] Parsing function(s).
+ * @param {Object} [fs] File system implementation.
  * @returns {Promise<Configuration>} Configuration object.
  */
-function readConfigPromise(file, parsers) {
+function readConfigPromise(file, parsers, fs) {
   // @ts-ignore
-  return readConfigPromisify(file, parsers);
+  return readConfigPromisify(file, parsers, fs);
 }
 
 /**
@@ -1015,12 +1068,16 @@ function readConfigPromise(file, parsers) {
  *
  * @param {string} file Configuration file name.
  * @param {ConfigurationParser[]} [parsers] Parsing function(s).
+ * @param {Object} [fs] File system implementation.
  * @returns {Configuration} Configuration object.
+ * @throws An Error if processing fails.
  */
-function readConfigSync(file, parsers) {
+function readConfigSync(file, parsers, fs) {
+  if (!fs) {
+    fs = require("fs");
+  }
   // Read file
-  // @ts-ignore
-  const content = fs.readFileSync(file, helpers.utf8Encoding);
+  const content = fs.readFileSync(file, "utf8");
   // Try to parse file
   const { config, message } = parseConfiguration(file, content, parsers);
   if (!config) {
@@ -1030,9 +1087,9 @@ function readConfigSync(file, parsers) {
   const configExtends = config.extends;
   if (configExtends) {
     delete config.extends;
-    const resolvedExtends = resolveConfigExtends(file, configExtends);
+    const resolvedExtends = resolveConfigExtendsSync(file, configExtends, fs);
     return {
-      ...readConfigSync(resolvedExtends, parsers),
+      ...readConfigSync(resolvedExtends, parsers, fs),
       ...config
     };
   }
@@ -1155,6 +1212,7 @@ module.exports = markdownlint;
  * @property {boolean} [noInlineConfig] True to ignore HTML directives.
  * @property {number} [resultVersion] Results object version.
  * @property {Plugin[]} [markdownItPlugins] Additional plugins.
+ * @property {Object} [fs] File system implementation.
  */
 
 /**
@@ -1196,13 +1254,14 @@ module.exports = markdownlint;
  * Fix information.
  *
  * @typedef {Object} FixInfo
+ * @property {number} [lineNumber] Line number (1-based).
  * @property {number} [editColumn] Column of the fix (1-based).
  * @property {number} [deleteCount] Count of characters to delete.
  * @property {string} [insertText] Text to insert (after deleting).
  */
 
 /**
- * Called with the result of the lint operation.
+ * Called with the result of the lint function.
  *
  * @callback LintCallback
  * @param {Error | null} err Error object or null.
@@ -1232,10 +1291,19 @@ module.exports = markdownlint;
  */
 
 /**
- * Called with the result of the readConfig operation.
+ * Called with the result of the readConfig function.
  *
  * @callback ReadConfigCallback
  * @param {Error | null} err Error object or null.
  * @param {Configuration} [config] Configuration object.
  * @returns {void}
  */
+
+/**
+ * Called with the result of the resolveConfigExtends function.
+ *
+ * @callback ResolveConfigExtendsCallback
+ * @param {Error | null} err Error object or null.
+ * @param {string} [path] Resolved path to file.
+ * @returns {void}
+ */

package/lib/md010.js

@@ -14,6 +14,10 @@ module.exports = {
   "function": function MD010(params, onError) {
     const codeBlocks = params.config.code_blocks;
     const includeCodeBlocks = (codeBlocks === undefined) ? true : !!codeBlocks;
+    const spacesPerTab = params.config.spaces_per_tab;
+    const spaceMultiplier = (spacesPerTab === undefined) ?
+      1 :
+      Math.max(0, Number(spacesPerTab));
     forEachLine(lineMetadata(), (line, lineIndex, inCode) => {
       if (!inCode || includeCodeBlocks) {
         let match = null;
@@ -29,7 +33,7 @@ module.exports = {
             {
               "editColumn": column,
               "deleteCount": length,
-              "insertText": "".padEnd(length)
+              "insertText": "".padEnd(length * spaceMultiplier)
             });
         }
       }