markdownlint 0.12.0 → 0.14.2

package/{lib/shared.js → helpers/helpers.js}

@@ -7,7 +7,8 @@
 module.exports.newLineRe = /\r[\n\u0085]?|[\n\u2424\u2028\u0085]/;
 
 // Regular expression for matching common front matter (YAML and TOML)
-module.exports.frontMatterRe = /^(---|\+\+\+)$[^]*?^\1$(\r\n|\r|\n|$)/m;
+module.exports.frontMatterRe =
+  /((^---$[^]*?^---$)|(^\+\+\+$[^]*?^(\+\+\+|\.\.\.)$))(\r\n|\r|\n|$)/m;
 
 // Regular expression for matching inline disable/enable comments
 const inlineCommentRe =
@@ -23,31 +24,6 @@ module.exports.orderedListItemMarkerRe = /^[\s>]*0*(\d+)[.)]/;
 // readFile options for reading with the UTF-8 encoding
 module.exports.utf8Encoding = { "encoding": "utf8" };
 
-// Trims whitespace from the left (start) of a string
-function trimLeft(str) {
-  return str.replace(/^\s*/, "");
-}
-module.exports.trimLeft = trimLeft;
-
-// Trims whitespace from the right (end) of a string
-module.exports.trimRight = function trimRight(str) {
-  return str.replace(/\s*$/, "");
-};
-
-// Applies key/value pairs from src to dst, returning dst
-function assign(dst, src) {
-  Object.keys(src).forEach(function forKey(key) {
-    dst[key] = src[key];
-  });
-  return dst;
-}
-module.exports.assign = assign;
-
-// Clones the key/value pairs of obj, returning the clone
-module.exports.clone = function clone(obj) {
-  return assign({}, obj);
-};
-
 // Returns true iff the input is a number
 module.exports.isNumber = function isNumber(obj) {
   return typeof obj === "number";
@@ -63,6 +39,31 @@ module.exports.isEmptyString = function isEmptyString(str) {
   return str.length === 0;
 };
 
+// Returns true iff the input line is blank (no content)
+// Example: Contains nothing, whitespace, or comments
+const blankLineRe = />|(?:<!--.*?-->)/g;
+module.exports.isBlankLine = function isBlankLine(line) {
+  return !line || !line.trim() || !line.replace(blankLineRe, "").trim();
+};
+
+// Returns true iff the sorted array contains the specified element
+module.exports.includesSorted = function includesSorted(array, element) {
+  let left = 0;
+  let right = array.length - 1;
+  while (left <= right) {
+    /* eslint-disable no-bitwise */
+    const mid = (left + right) >> 1;
+    if (array[mid] < element) {
+      left = mid + 1;
+    } else if (array[mid] > element) {
+      right = mid - 1;
+    } else {
+      return true;
+    }
+  }
+  return false;
+};
+
 // Replaces the text of all properly-formatted HTML comments with whitespace
 // This preserves the line/column information for the rest of the document
 // Trailing whitespace is avoided with a '\' character in the last column
@@ -75,13 +76,13 @@ module.exports.clearHtmlCommentText = function clearHtmlCommentText(text) {
     let j = text.indexOf(htmlCommentEnd, i);
     if (j === -1) {
       j = text.length;
-      text += "\\";
+      text += "\\\n";
     }
     const comment = text.slice(i + htmlCommentBegin.length, j);
     if ((comment.length > 0) &&
         (comment[0] !== ">") &&
         (comment[comment.length - 1] !== "-") &&
-        (comment.indexOf("--") === -1) &&
+        !comment.includes("--") &&
         (text.slice(i, j + htmlCommentEnd.length)
           .search(inlineCommentRe) === -1)) {
       const blanks = comment
@@ -100,10 +101,23 @@ module.exports.escapeForRegExp = function escapeForRegExp(str) {
   return str.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
 };
 
+// Un-escapes Markdown content (simple algorithm; not a parser)
+const escapedMarkdownRe = /\\./g;
+module.exports.unescapeMarkdown =
+  function unescapeMarkdown(markdown, replacement) {
+    return markdown.replace(escapedMarkdownRe, (match) => {
+      const char = match[1];
+      if ("!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~".includes(char)) {
+        return replacement || char;
+      }
+      return match;
+    });
+  };
+
 // Returns the indent for a token
 function indentFor(token) {
   const line = token.line.replace(/^[\s>]*(> |>)/, "");
-  return line.length - trimLeft(line).length;
+  return line.length - line.trimLeft().length;
 }
 module.exports.indentFor = indentFor;
 
@@ -119,24 +133,17 @@ module.exports.headingStyleFor = function headingStyleFor(token) {
 };
 
 // Calls the provided function for each matching token
-function filterTokens(params, type, callback) {
+function filterTokens(params, type, handler) {
   params.tokens.forEach(function forToken(token) {
     if (token.type === type) {
-      callback(token);
+      handler(token);
     }
   });
 }
 module.exports.filterTokens = filterTokens;
 
-let tokenCache = null;
-// Caches line metadata and flattened lists for reuse
-function makeTokenCache(params) {
-  if (!params) {
-    tokenCache = null;
-    return;
-  }
-
-  // Initialize line metadata array
+// Get line metadata array
+module.exports.getLineMetadata = function getLineMetadata(params) {
   const lineMetadata = params.lines.map(function mapLine(line, index) {
     return [ line, index, false, 0, false ];
   });
@@ -157,8 +164,19 @@ function makeTokenCache(params) {
       lineMetadata[i][4] = true;
     }
   });
+  return lineMetadata;
+};
+
+// Calls the provided function for each line (with context)
+module.exports.forEachLine = function forEachLine(lineMetadata, handler) {
+  lineMetadata.forEach(function forMetadata(metadata) {
+    // Parameters: line, lineIndex, inCode, onFence, inTable
+    handler(...metadata);
+  });
+};
 
-  // Flatten lists
+// Returns (nested) lists as a flat array (in order)
+module.exports.flattenLists = function flattenLists(params) {
   const flattenedLists = [];
   const stack = [];
   let current = null;
@@ -195,38 +213,23 @@ function makeTokenCache(params) {
       lastWithMap = token;
     }
   });
-
-  // Cache results
-  tokenCache = {
-    "params": params,
-    "lineMetadata": lineMetadata,
-    "flattenedLists": flattenedLists
-  };
-}
-module.exports.makeTokenCache = makeTokenCache;
-
-// Calls the provided function for each line (with context)
-module.exports.forEachLine = function forEachLine(callback) {
-  tokenCache.lineMetadata.forEach(function forMetadata(metadata) {
-    // Parameters: line, lineIndex, inCode, onFence, inTable
-    callback.apply(this, metadata);
-  });
+  return flattenedLists;
 };
 
 // Calls the provided function for each specified inline child token
 module.exports.forEachInlineChild =
-function forEachInlineChild(params, type, callback) {
+function forEachInlineChild(params, type, handler) {
   filterTokens(params, "inline", function forToken(token) {
     token.children.forEach(function forChild(child) {
       if (child.type === type) {
-        callback(child, token);
+        handler(child, token);
       }
     });
   });
 };
 
 // Calls the provided function for each heading's content
-module.exports.forEachHeading = function forEachHeading(params, callback) {
+module.exports.forEachHeading = function forEachHeading(params, handler) {
   let heading = null;
   params.tokens.forEach(function forToken(token) {
     if (token.type === "heading_open") {
@@ -234,14 +237,14 @@ module.exports.forEachHeading = function forEachHeading(params, callback) {
     } else if (token.type === "heading_close") {
       heading = null;
     } else if ((token.type === "inline") && heading) {
-      callback(heading, token.content);
+      handler(heading, token.content);
     }
   });
 };
 
 // Calls the provided function for each inline code span's content
 module.exports.forEachInlineCodeSpan =
-  function forEachInlineCodeSpan(input, callback) {
+  function forEachInlineCodeSpan(input, handler) {
     let currentLine = 0;
     let currentColumn = 0;
     let index = 0;
@@ -265,7 +268,7 @@ module.exports.forEachInlineCodeSpan =
             (startColumn >= 0) &&
             (tickCount === currentTicks)) {
             // Found end backticks; invoke callback for code span
-            callback(
+            handler(
               input.substring(startIndex, index - currentTicks),
               startLine, startColumn, tickCount);
             startIndex = -1;
@@ -302,11 +305,6 @@ module.exports.forEachInlineCodeSpan =
     }
   };
 
-// Returns (nested) lists as a flat array (in order)
-module.exports.flattenLists = function flattenLists() {
-  return tokenCache.flattenedLists;
-};
-
 // Adds a generic error object via the onError callback
 function addError(onError, lineNumber, detail, context, range) {
   onError({
@@ -320,32 +318,32 @@ module.exports.addError = addError;
 
 // Adds an error object with details conditionally via the onError callback
 module.exports.addErrorDetailIf = function addErrorDetailIf(
-  onError, lineNumber, expected, actual, detail, range) {
+  onError, lineNumber, expected, actual, detail, context, range) {
   if (expected !== actual) {
     addError(
       onError,
       lineNumber,
       "Expected: " + expected + "; Actual: " + actual +
         (detail ? "; " + detail : ""),
-      null,
+      context,
       range);
   }
 };
 
 // Adds an error object with context via the onError callback
 module.exports.addErrorContext =
-function addErrorContext(onError, lineNumber, context, left, right, range) {
-  if (context.length <= 30) {
-    // Nothing to do
-  } else if (left && right) {
-    context = context.substr(0, 15) + "..." + context.substr(-15);
-  } else if (right) {
-    context = "..." + context.substr(-30);
-  } else {
-    context = context.substr(0, 30) + "...";
-  }
-  addError(onError, lineNumber, null, context, range);
-};
+  function addErrorContext(onError, lineNumber, context, left, right, range) {
+    if (context.length <= 30) {
+      // Nothing to do
+    } else if (left && right) {
+      context = context.substr(0, 15) + "..." + context.substr(-15);
+    } else if (right) {
+      context = "..." + context.substr(-30);
+    } else {
+      context = context.substr(0, 30) + "...";
+    }
+    addError(onError, lineNumber, null, context, range);
+  };
 
 // Returns a range object for a line by applying a RegExp
 module.exports.rangeFromRegExp = function rangeFromRegExp(line, regexp) {
@@ -362,3 +360,14 @@ module.exports.rangeFromRegExp = function rangeFromRegExp(line, regexp) {
   }
   return range;
 };
+
+// Determines if the front matter includes a title
+module.exports.frontMatterHasTitle =
+  function frontMatterHasTitle(frontMatterLines, frontMatterTitlePattern) {
+    const ignoreFrontMatter =
+      (frontMatterTitlePattern !== undefined) && !frontMatterTitlePattern;
+    const frontMatterTitleRe =
+      new RegExp(frontMatterTitlePattern || "^\\s*title\\s*[:=]", "i");
+    return !ignoreFrontMatter &&
+      frontMatterLines.some((line) => frontMatterTitleRe.test(line));
+  };

package/helpers/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "markdownlint-rule-helpers",
+  "version": "0.2.1",
+  "description": "A collection of markdownlint helper functions for custom rules",
+  "main": "helpers.js",
+  "author": "David Anson (https://dlaa.me/)",
+  "license": "MIT",
+  "homepage": "https://github.com/DavidAnson/markdownlint",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DavidAnson/markdownlint.git"
+  },
+  "bugs": "https://github.com/DavidAnson/markdownlint/issues",
+  "keywords": [
+    "markdownlint",
+    "markdownlint-rule"
+  ]
+}

package/lib/cache.js

@@ -0,0 +1,24 @@
+// @ts-check
+
+"use strict";
+
+let lineMetadata = null;
+module.exports.lineMetadata = (value) => {
+  if (value) {
+    lineMetadata = value;
+  }
+  return lineMetadata;
+};
+
+let flattenedLists = null;
+module.exports.flattenedLists = (value) => {
+  if (value) {
+    flattenedLists = value;
+  }
+  return flattenedLists;
+};
+
+module.exports.clear = () => {
+  lineMetadata = null;
+  flattenedLists = null;
+};

package/lib/markdownlint.js

@@ -7,7 +7,10 @@ const path = require("path");
 const { URL } = require("url");
 const markdownIt = require("markdown-it");
 const rules = require("./rules");
-const shared = require("./shared");
+const helpers = require("../helpers");
+const cache = require("./cache");
+
+const deprecatedRuleNames = [ "MD002" ];
 
 // Validates the list of rules for structure and reuse
 function validateRuleList(ruleList) {
@@ -28,7 +31,7 @@ function validateRuleList(ruleList) {
       const value = rule[property];
       if (!result &&
         (!value || !Array.isArray(value) || (value.length === 0) ||
-         !value.every(shared.isString) || value.some(shared.isEmptyString))) {
+         !value.every(helpers.isString) || value.some(helpers.isEmptyString))) {
         result = newError(property);
       }
     });
@@ -72,7 +75,7 @@ function validateRuleList(ruleList) {
 // Class for results with toString for pretty display
 function newResults(ruleList) {
   function Results() {}
-  Results.prototype.toString = function resultsToString(useAlias) {
+  Results.prototype.toString = function toString(useAlias) {
     const that = this;
     let ruleNameToRule = null;
     const results = [];
@@ -131,7 +134,7 @@ function removeFrontMatter(content, frontMatter) {
     if (frontMatterMatch && !frontMatterMatch.index) {
       const contentMatched = frontMatterMatch[0];
       content = content.slice(contentMatched.length);
-      frontMatterLines = contentMatched.split(shared.newLineRe);
+      frontMatterLines = contentMatched.split(helpers.newLineRe);
       if (frontMatterLines.length &&
           (frontMatterLines[frontMatterLines.length - 1] === "")) {
         frontMatterLines.length--;
@@ -164,7 +167,7 @@ function annotateTokens(tokens, lines) {
       token.line = lines[token.map[0]];
       token.lineNumber = token.map[0] + 1;
       // Trim bottom of token to exclude whitespace lines
-      while (token.map[1] && !(lines[token.map[1] - 1].trim())) {
+      while (token.map[1] && !((lines[token.map[1] - 1] || "").trim())) {
         token.map[1]--;
       }
       // Annotate children with lineNumber
@@ -212,16 +215,19 @@ function mapAliasToRuleNames(ruleList) {
 
 // Apply (and normalize) config
 function getEffectiveConfig(ruleList, config, aliasToRuleNames) {
-  const defaultKey = Object.keys(config).filter(function forKey(key) {
-    return key.toUpperCase() === "DEFAULT";
-  });
+  const defaultKey = Object.keys(config).filter(
+    (key) => key.toUpperCase() === "DEFAULT"
+  );
   const ruleDefault = (defaultKey.length === 0) || !!config[defaultKey[0]];
   const effectiveConfig = {};
-  ruleList.forEach(function forRule(rule) {
+  ruleList.forEach((rule) => {
     const ruleName = rule.names[0].toUpperCase();
     effectiveConfig[ruleName] = ruleDefault;
   });
-  Object.keys(config).forEach(function forKey(key) {
+  deprecatedRuleNames.forEach((ruleName) => {
+    effectiveConfig[ruleName] = false;
+  });
+  Object.keys(config).forEach((key) => {
     let value = config[key];
     if (value) {
       if (!(value instanceof Object)) {
@@ -231,7 +237,7 @@ function getEffectiveConfig(ruleList, config, aliasToRuleNames) {
       value = false;
     }
     const keyUpper = key.toUpperCase();
-    (aliasToRuleNames[keyUpper] || []).forEach(function forRule(ruleName) {
+    (aliasToRuleNames[keyUpper] || []).forEach((ruleName) => {
       effectiveConfig[ruleName] = value;
     });
   });
@@ -263,12 +269,12 @@ function getEnabledRulesPerLineNumber(
   const enabledRulesPerLineNumber = new Array(1 + frontMatterLines.length);
   lines.forEach(function forLine(line) {
     if (!noInlineConfig) {
-      let match = shared.inlineCommentRe.exec(line);
+      let match = helpers.inlineCommentRe.exec(line);
       if (match) {
-        enabledRules = shared.clone(enabledRules);
+        enabledRules = { ...enabledRules };
         while (match) {
           forMatch(match);
-          match = shared.inlineCommentRe.exec(line);
+          match = helpers.inlineCommentRe.exec(line);
         }
       }
     }
@@ -295,6 +301,7 @@ function lintContent(
   md,
   config,
   frontMatter,
+  handleRuleFailures,
   noInlineConfig,
   resultVersion,
   callback) {
@@ -304,10 +311,10 @@ function lintContent(
   const removeFrontMatterResult = removeFrontMatter(content, frontMatter);
   const frontMatterLines = removeFrontMatterResult.frontMatterLines;
   // Ignore the content of HTML comments
-  content = shared.clearHtmlCommentText(removeFrontMatterResult.content);
+  content = helpers.clearHtmlCommentText(removeFrontMatterResult.content);
   // Parse content into tokens and lines
   const tokens = md.parse(content, {});
-  const lines = content.split(shared.newLineRe);
+  const lines = content.split(helpers.newLineRe);
   annotateTokens(tokens, lines);
   const aliasToRuleNames = mapAliasToRuleNames(ruleList);
   const effectiveConfig =
@@ -322,7 +329,8 @@ function lintContent(
     lines,
     frontMatterLines
   };
-  shared.makeTokenCache(params);
+  cache.lineMetadata(helpers.getLineMetadata(params));
+  cache.flattenedLists(helpers.flattenLists(params));
   // Function to run for each rule
   const result = (resultVersion === 0) ? {} : [];
   function forRule(rule) {
@@ -337,23 +345,28 @@ function lintContent(
     const errors = [];
     function onError(errorInfo) {
       if (!errorInfo ||
-        !errorInfo.lineNumber ||
-        !shared.isNumber(errorInfo.lineNumber)) {
+        !helpers.isNumber(errorInfo.lineNumber) ||
+        (errorInfo.lineNumber < 1) ||
+        (errorInfo.lineNumber > lines.length)) {
         throwError("lineNumber");
       }
       if (errorInfo.detail &&
-        !shared.isString(errorInfo.detail)) {
+        !helpers.isString(errorInfo.detail)) {
         throwError("detail");
       }
       if (errorInfo.context &&
-        !shared.isString(errorInfo.context)) {
+        !helpers.isString(errorInfo.context)) {
         throwError("context");
       }
       if (errorInfo.range &&
         (!Array.isArray(errorInfo.range) ||
          (errorInfo.range.length !== 2) ||
-         !shared.isNumber(errorInfo.range[0]) ||
-         !shared.isNumber(errorInfo.range[1]))) {
+         !helpers.isNumber(errorInfo.range[0]) ||
+         (errorInfo.range[0] < 1) ||
+         !helpers.isNumber(errorInfo.range[1]) ||
+         (errorInfo.range[1] < 1) ||
+         ((errorInfo.range[0] + errorInfo.range[1] - 1) >
+          lines[errorInfo.lineNumber - 1].length))) {
         throwError("range");
       }
       errors.push({
@@ -364,7 +377,18 @@ function lintContent(
       });
     }
     // Call (possibly external) rule function
-    rule.function(params, onError);
+    if (handleRuleFailures) {
+      try {
+        rule.function(params, onError);
+      } catch (ex) {
+        onError({
+          "lineNumber": 1,
+          "detail": `This rule threw an exception: ${ex.message}`
+        });
+      }
+    } else {
+      rule.function(params, onError);
+    }
     // Record any errors (significant performance benefit from length check)
     if (errors.length) {
       errors.sort(lineNumberComparison);
@@ -406,11 +430,11 @@ function lintContent(
   try {
     ruleList.forEach(forRule);
   } catch (ex) {
-    shared.makeTokenCache(null);
+    cache.clear();
     return callback(ex);
   }
-  shared.makeTokenCache(null);
-  callback(null, result);
+  cache.clear();
+  return callback(null, result);
 }
 
 // Lints a single file
@@ -420,6 +444,7 @@ function lintFile(
   md,
   config,
   frontMatter,
+  handleRuleFailures,
   noInlineConfig,
   resultVersion,
   synchronous,
@@ -428,14 +453,14 @@ function lintFile(
     if (err) {
       return callback(err);
     }
-    lintContent(ruleList, file, content, md, config, frontMatter,
-      noInlineConfig, resultVersion, callback);
+    return lintContent(ruleList, file, content, md, config, frontMatter,
+      handleRuleFailures, noInlineConfig, resultVersion, callback);
   }
   // Make a/synchronous call to read file
   if (synchronous) {
-    lintContentWrapper(null, fs.readFileSync(file, shared.utf8Encoding));
+    lintContentWrapper(null, fs.readFileSync(file, helpers.utf8Encoding));
   } else {
-    fs.readFile(file, shared.utf8Encoding, lintContentWrapper);
+    fs.readFile(file, helpers.utf8Encoding, lintContentWrapper);
   }
 }
 
@@ -459,7 +484,8 @@ function lintInput(options, synchronous, callback) {
   const stringsKeys = Object.keys(strings);
   const config = options.config || { "default": true };
   const frontMatter = (options.frontMatter === undefined) ?
-    shared.frontMatterRe : options.frontMatter;
+    helpers.frontMatterRe : options.frontMatter;
+  const handleRuleFailures = !!options.handleRuleFailures;
   const noInlineConfig = !!options.noInlineConfig;
   const resultVersion = (options.resultVersion === undefined) ?
     2 : options.resultVersion;
@@ -471,6 +497,7 @@ function lintInput(options, synchronous, callback) {
   });
   const results = newResults(ruleList);
   // Helper to lint the next string or file
+  /* eslint-disable consistent-return */
   function lintNextItem() {
     let iterating = true;
     let item = null;
@@ -480,9 +507,7 @@ function lintInput(options, synchronous, callback) {
         return callback(err);
       }
       results[item] = result;
-      if (!iterating) {
-        lintNextItem();
-      }
+      return iterating || lintNextItem();
     }
     while (iterating) {
       if ((item = stringsKeys.shift())) {
@@ -493,6 +518,7 @@ function lintInput(options, synchronous, callback) {
           md,
           config,
           frontMatter,
+          handleRuleFailures,
           noInlineConfig,
           resultVersion,
           lintNextItemCallback);
@@ -504,6 +530,7 @@ function lintInput(options, synchronous, callback) {
           md,
           config,
           frontMatter,
+          handleRuleFailures,
           noInlineConfig,
           resultVersion,
           synchronous,
@@ -513,7 +540,7 @@ function lintInput(options, synchronous, callback) {
       }
     }
   }
-  lintNextItem();
+  return lintNextItem();
 }
 
 /**
@@ -584,7 +611,7 @@ function readConfig(file, parsers, callback) {
     parsers = null;
   }
   // Read file
-  fs.readFile(file, shared.utf8Encoding, (err, content) => {
+  fs.readFile(file, helpers.utf8Encoding, (err, content) => {
     if (err) {
       return callback(err);
     }
@@ -598,15 +625,17 @@ function readConfig(file, parsers, callback) {
     if (configExtends) {
       delete config.extends;
       const extendsFile = path.resolve(path.dirname(file), configExtends);
-      readConfig(extendsFile, parsers, (errr, extendsConfig) => {
+      return readConfig(extendsFile, parsers, (errr, extendsConfig) => {
         if (errr) {
           return callback(errr);
         }
-        callback(null, shared.assign(extendsConfig, config));
+        return callback(null, {
+          ...extendsConfig,
+          ...config
+        });
       });
-    } else {
-      callback(null, config);
     }
+    return callback(null, config);
   });
 }
 
@@ -619,7 +648,7 @@ function readConfig(file, parsers, callback) {
  */
 function readConfigSync(file, parsers) {
   // Read file
-  const content = fs.readFileSync(file, shared.utf8Encoding);
+  const content = fs.readFileSync(file, helpers.utf8Encoding);
   // Try to parse file
   const { config, message } = parseConfiguration(file, content, parsers);
   if (!config) {
@@ -629,9 +658,13 @@ function readConfigSync(file, parsers) {
   const configExtends = config.extends;
   if (configExtends) {
     delete config.extends;
-    return shared.assign(
-      readConfigSync(path.resolve(path.dirname(file), configExtends), parsers),
-      config);
+    return {
+      ...readConfigSync(
+        path.resolve(path.dirname(file), configExtends),
+        parsers
+      ),
+      ...config
+    };
   }
   return config;
 }