markdownlint 0.25.1 → 0.26.0

package/lib/md044.js

@@ -3,8 +3,10 @@
 "use strict";
 
 const { addErrorDetailIf, bareUrlRe, escapeForRegExp, forEachLine,
-  overlapsAnyRange, linkRe, linkReferenceRe } = require("../helpers");
-const { codeBlockAndSpanRanges, lineMetadata } = require("./cache");
+  forEachLink, withinAnyRange, linkReferenceDefinitionRe } =
+  require("../helpers");
+const { codeBlockAndSpanRanges, htmlElementRanges, lineMetadata } =
+  require("./cache");
 
 module.exports = {
   "names": [ "MD044", "proper-names" ],
@@ -15,29 +17,35 @@ module.exports = {
     names = Array.isArray(names) ? names : [];
     names.sort((a, b) => (b.length - a.length) || a.localeCompare(b));
     const codeBlocks = params.config.code_blocks;
-    const includeCodeBlocks = (codeBlocks === undefined) ? true : !!codeBlocks;
+    const includeCodeBlocks =
+      (codeBlocks === undefined) ? true : !!codeBlocks;
+    const htmlElements = params.config.html_elements;
+    const includeHtmlElements =
+      (htmlElements === undefined) ? true : !!htmlElements;
     const exclusions = [];
     forEachLine(lineMetadata(), (line, lineIndex) => {
-      if (linkReferenceRe.test(line)) {
+      if (linkReferenceDefinitionRe.test(line)) {
         exclusions.push([ lineIndex, 0, line.length ]);
       } else {
         let match = null;
         while ((match = bareUrlRe.exec(line)) !== null) {
           exclusions.push([ lineIndex, match.index, match[0].length ]);
         }
-        while ((match = linkRe.exec(line)) !== null) {
-          const [ , text, destination ] = match;
+        forEachLink(line, (index, _, text, destination) => {
           if (destination) {
             exclusions.push(
-              [ lineIndex, match.index + text.length, destination.length ]
+              [ lineIndex, index + text.length, destination.length ]
             );
           }
-        }
+        });
       }
     });
     if (!includeCodeBlocks) {
       exclusions.push(...codeBlockAndSpanRanges());
     }
+    if (!includeHtmlElements) {
+      exclusions.push(...htmlElementRanges());
+    }
     for (const name of names) {
       const escapedName = escapeForRegExp(name);
       const startNamePattern = /^\W/.test(name) ? "" : "\\b_*";
@@ -52,7 +60,10 @@ module.exports = {
             const [ , leftMatch, nameMatch ] = match;
             const index = match.index + leftMatch.length;
             const length = nameMatch.length;
-            if (!overlapsAnyRange(exclusions, lineIndex, index, length)) {
+            if (
+              !withinAnyRange(exclusions, lineIndex, index, length) &&
+              !names.includes(nameMatch)
+            ) {
               addErrorDetailIf(
                 onError,
                 lineIndex + 1,

package/lib/md046.js

@@ -15,18 +15,19 @@ module.exports = {
   "tags": [ "code" ],
   "function": function MD046(params, onError) {
     let expectedStyle = String(params.config.style || "consistent");
-    params.tokens
-      .filter((token) => token.type === "code_block" || token.type === "fence")
-      .forEach((token) => {
-        const { lineNumber, type } = token;
-        if (expectedStyle === "consistent") {
-          expectedStyle = tokenTypeToStyle[type];
-        }
-        addErrorDetailIf(
-          onError,
-          lineNumber,
-          expectedStyle,
-          tokenTypeToStyle[type]);
-      });
+    const codeBlocksAndFences = params.tokens.filter(
+      (token) => (token.type === "code_block") || (token.type === "fence")
+    );
+    for (const token of codeBlocksAndFences) {
+      const { lineNumber, type } = token;
+      if (expectedStyle === "consistent") {
+        expectedStyle = tokenTypeToStyle[type];
+      }
+      addErrorDetailIf(
+        onError,
+        lineNumber,
+        expectedStyle,
+        tokenTypeToStyle[type]);
+    }
   }
 };

package/lib/md048.js

@@ -11,19 +11,18 @@ module.exports = {
   "function": function MD048(params, onError) {
     const style = String(params.config.style || "consistent");
     let expectedStyle = style;
-    params.tokens
-      .filter((token) => token.type === "fence")
-      .forEach((fenceToken) => {
-        const { lineNumber, markup } = fenceToken;
-        if (expectedStyle === "consistent") {
-          expectedStyle = fencedCodeBlockStyleFor(markup);
-        }
-        addErrorDetailIf(
-          onError,
-          lineNumber,
-          expectedStyle,
-          fencedCodeBlockStyleFor(markup)
-        );
-      });
+    const fenceTokens = params.tokens.filter((token) => token.type === "fence");
+    for (const fenceToken of fenceTokens) {
+      const { lineNumber, markup } = fenceToken;
+      if (expectedStyle === "consistent") {
+        expectedStyle = fencedCodeBlockStyleFor(markup);
+      }
+      addErrorDetailIf(
+        onError,
+        lineNumber,
+        expectedStyle,
+        fencedCodeBlockStyleFor(markup)
+      );
+    }
   }
 };

package/lib/md049-md050.js

@@ -0,0 +1,73 @@
+// @ts-check
+
+"use strict";
+
+const { addError, emphasisOrStrongStyleFor, forEachInlineChild,
+  getNextChildToken, getRangeAndFixInfoIfFound } = require("../helpers");
+
+const impl = (params, onError, tagPrefix, asterisk, underline, style) => {
+  let lastLineNumber = -1;
+  const instances = new Map();
+  forEachInlineChild(params, `${tagPrefix}_open`, (token, parent) => {
+    const { lineNumber, markup } = token;
+    const markupStyle = emphasisOrStrongStyleFor(markup);
+    if (style === "consistent") {
+      style = markupStyle;
+    }
+    if (style !== markupStyle) {
+      let rangeAndFixInfo = {};
+      const contentToken = getNextChildToken(
+        parent, token, "text", `${tagPrefix}_close`
+      );
+      if (contentToken) {
+        const { content } = contentToken;
+        const actual = `${markup}${content}${markup}`;
+        const expectedMarkup =
+          (style === "asterisk") ? asterisk : underline;
+        const expected = `${expectedMarkup}${content}${expectedMarkup}`;
+        if (lastLineNumber !== lineNumber) {
+          lastLineNumber = lineNumber;
+          instances.clear();
+        }
+        const instance = (instances.get(expected) || 0) + 1;
+        instances.set(expected, instance);
+        rangeAndFixInfo = getRangeAndFixInfoIfFound(
+          params.lines,
+          lineNumber - 1,
+          actual,
+          expected,
+          instance
+        );
+      }
+      addError(
+        onError,
+        lineNumber,
+        `Expected: ${style}; Actual: ${markupStyle}`,
+        null,
+        rangeAndFixInfo.range,
+        rangeAndFixInfo.fixInfo
+      );
+    }
+  });
+};
+
+module.exports = [
+  {
+    "names": [ "MD049", "emphasis-style" ],
+    "description": "Emphasis style should be consistent",
+    "tags": [ "emphasis" ],
+    "function": function MD049(params, onError) {
+      const style = String(params.config.style || "consistent");
+      return impl(params, onError, "em", "*", "_", style);
+    }
+  },
+  {
+    "names": [ "MD050", "strong-style" ],
+    "description": "Strong style should be consistent",
+    "tags": [ "emphasis" ],
+    "function": function MD050(params, onError) {
+      const style = String(params.config.style || "consistent");
+      return impl(params, onError, "strong", "**", "__", style);
+    }
+  }
+];

package/lib/md051.js

@@ -0,0 +1,84 @@
+// @ts-check
+
+"use strict";
+
+const { addError, escapeForRegExp, filterTokens, forEachInlineChild,
+  forEachHeading, htmlElementRe } = require("../helpers");
+
+// Regular expression for identifying HTML anchor names
+const identifierRe = /(?:id|name)\s*=\s*['"]?([^'"\s>]+)/iu;
+
+/**
+ * Converts a Markdown heading into an HTML fragment according to the rules
+ * used by GitHub.
+ *
+ * @param {Object} inline Inline token for heading.
+ * @returns {string} Fragment string for heading.
+ */
+function convertHeadingToHTMLFragment(inline) {
+  const inlineText = inline.children.map((token) => token.content).join("");
+  return "#" + encodeURIComponent(
+    inlineText
+      .toLowerCase()
+      // RegExp source with Ruby's \p{Word} expanded into its General Categories
+      // eslint-disable-next-line max-len
+      // https://github.com/gjtorikian/html-pipeline/blob/main/lib/html/pipeline/toc_filter.rb
+      // https://ruby-doc.org/core-3.0.2/Regexp.html
+      .replace(
+        /[^\p{Letter}\p{Mark}\p{Number}\p{Connector_Punctuation}\- ]/gu,
+        ""
+      )
+      .replace(/ /gu, "-")
+  );
+}
+
+module.exports = {
+  "names": [ "MD051", "link-fragments" ],
+  "description": "Link fragments should be valid",
+  "tags": [ "links" ],
+  "function": function MD051(params, onError) {
+    const fragments = new Map();
+    // Process headings
+    forEachHeading(params, (heading, content, inline) => {
+      const fragment = convertHeadingToHTMLFragment(inline);
+      const count = fragments.get(fragment) || 0;
+      if (count) {
+        fragments.set(`${fragment}-${count}`, 0);
+      }
+      fragments.set(fragment, count + 1);
+    });
+    // Process HTML anchors
+    const processHtmlToken = (token) => {
+      let match = null;
+      while ((match = htmlElementRe.exec(token.content)) !== null) {
+        const [ tag, , element ] = match;
+        if (element.toLowerCase() === "a") {
+          const idMatch = identifierRe.exec(tag);
+          if (idMatch) {
+            fragments.set(`#${idMatch[1]}`, 0);
+          }
+        }
+      }
+    };
+    filterTokens(params, "html_block", processHtmlToken);
+    forEachInlineChild(params, "html_inline", processHtmlToken);
+    // Process link fragments
+    forEachInlineChild(params, "link_open", (token) => {
+      const { attrs, lineNumber, line } = token;
+      const href = attrs.find((attr) => attr[0] === "href");
+      const id = href && href[1];
+      if (id && (id.length > 1) && (id[0] === "#") && !fragments.has(id)) {
+        let context = id;
+        let range = null;
+        const match = line.match(
+          new RegExp(`\\[.*?\\]\\(${escapeForRegExp(context)}\\)`)
+        );
+        if (match) {
+          context = match[0];
+          range = [ match.index + 1, match[0].length ];
+        }
+        addError(onError, lineNumber, null, context, range);
+      }
+    });
+  }
+};

package/lib/md052.js

@@ -0,0 +1,35 @@
+// @ts-check
+
+"use strict";
+
+const { addError } = require("../helpers");
+const { referenceLinkImageData } = require("./cache");
+
+module.exports = {
+  "names": [ "MD052", "reference-links-images" ],
+  "description":
+    "Reference links and images should use a label that is defined",
+  "tags": [ "images", "links" ],
+  "function": function MD052(params, onError) {
+    const { lines } = params;
+    const { references, definitions } = referenceLinkImageData();
+    // Look for links/images that use an undefined link reference
+    for (const reference of references.entries()) {
+      const [ label, datas ] = reference;
+      if (!definitions.has(label)) {
+        for (const data of datas) {
+          const [ lineIndex, index, length ] = data;
+          // Context will be incomplete if reporting for a multi-line link
+          const context = lines[lineIndex].slice(index, index + length);
+          addError(
+            onError,
+            lineIndex + 1,
+            `Missing link or image reference definition: "${label}"`,
+            context,
+            [ index + 1, context.length ]
+          );
+        }
+      }
+    }
+  }
+};

package/lib/md053.js

@@ -0,0 +1,52 @@
+// @ts-check
+
+"use strict";
+
+const { addError, ellipsify, linkReferenceDefinitionRe } =
+  require("../helpers");
+const { referenceLinkImageData } = require("./cache");
+
+module.exports = {
+  "names": [ "MD053", "link-image-reference-definitions" ],
+  "description": "Link and image reference definitions should be needed",
+  "tags": [ "images", "links" ],
+  "function": function MD053(params, onError) {
+    const { lines } = params;
+    const { references, shortcuts, definitions, duplicateDefinitions } =
+      referenceLinkImageData();
+    const singleLineDefinition = (line) => (
+      line.replace(linkReferenceDefinitionRe, "").trim().length > 0
+    );
+    const deleteFixInfo = {
+      "deleteCount": -1
+    };
+    // Look for unused link references (unreferenced by any link/image)
+    for (const definition of definitions.entries()) {
+      const [ label, lineIndex ] = definition;
+      if (!references.has(label) && !shortcuts.has(label)) {
+        const line = lines[lineIndex];
+        addError(
+          onError,
+          lineIndex + 1,
+          `Unused link or image reference definition: "${label}"`,
+          ellipsify(line),
+          [ 1, line.length ],
+          singleLineDefinition(line) ? deleteFixInfo : 0
+        );
+      }
+    }
+    // Look for duplicate link references (defined more than once)
+    for (const duplicateDefinition of duplicateDefinitions) {
+      const [ label, lineIndex ] = duplicateDefinition;
+      const line = lines[lineIndex];
+      addError(
+        onError,
+        lineIndex + 1,
+        `Duplicate link or image reference definition: "${label}"`,
+        ellipsify(line),
+        [ 1, line.length ],
+        singleLineDefinition(line) ? deleteFixInfo : 0
+      );
+    }
+  }
+};

package/lib/rules.js

@@ -49,13 +49,15 @@ const rules = [
   require("./md046"),
   require("./md047"),
   require("./md048"),
-  require("./md049"),
-  require("./md050")
+  ...require("./md049-md050"),
+  require("./md051"),
+  require("./md052"),
+  require("./md053")
 ];
-rules.forEach((rule) => {
+for (const rule of rules) {
   const name = rule.names[0].toLowerCase();
   // eslint-disable-next-line dot-notation
   rule["information"] =
     new URL(`${homepage}/blob/v${version}/doc/Rules.md#${name}`);
-});
+}
 module.exports = rules;

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "markdownlint",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "description": "A Node.js style checker and lint tool for Markdown/CommonMark files.",
+  "type": "commonjs",
   "main": "lib/markdownlint.js",
   "types": "lib/markdownlint.d.ts",
   "author": "David Anson (https://dlaa.me/)",
@@ -16,7 +17,7 @@
     "build-config": "npm run build-config-schema && npm run build-config-example",
     "build-config-example": "node schema/build-config-example.js",
     "build-config-schema": "node schema/build-config-schema.js",
-    "build-declaration": "tsc --allowJs --declaration --emitDeclarationOnly --resolveJsonModule lib/markdownlint.js && node scripts delete 'lib/{c,md,r}*.d.ts' 'helpers/*.d.ts'",
+    "build-declaration": "tsc --allowJs --declaration --emitDeclarationOnly --module commonjs --resolveJsonModule --target es2015 lib/markdownlint.js && node scripts delete 'lib/{c,md,r}*.d.ts' 'helpers/*.d.ts'",
     "build-demo": "node scripts copy node_modules/markdown-it/dist/markdown-it.min.js demo/markdown-it.min.js && cd demo && webpack --no-stats",
     "build-example": "npm install --no-save --ignore-scripts grunt grunt-cli gulp through2",
     "ci": "npm-run-all --continue-on-error --parallel build-config lint serial-declaration-demo test-cover && git diff --exit-code",
@@ -41,37 +42,39 @@
     "test-cover": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 npm test",
     "test-declaration": "cd example/typescript && tsc && node type-check.js",
     "test-extra": "ava --timeout=5m test/markdownlint-test-extra-parse.js test/markdownlint-test-extra-type.js",
+    "update-snapshots": "ava --update-snapshots test/markdownlint-test-scenarios.js",
     "upgrade": "npx --yes npm-check-updates --upgrade"
   },
   "engines": {
-    "node": ">=12"
+    "node": ">=14"
   },
   "dependencies": {
-    "markdown-it": "12.3.2"
+    "markdown-it": "13.0.1"
   },
   "devDependencies": {
-    "ava": "3.15.0",
-    "c8": "7.10.0",
-    "eslint": "8.5.0",
-    "eslint-plugin-jsdoc": "37.4.0",
+    "ava": "4.3.0",
+    "c8": "7.11.3",
+    "eslint": "8.18.0",
+    "eslint-plugin-es": "4.1.0",
+    "eslint-plugin-jsdoc": "39.3.3",
     "eslint-plugin-node": "11.1.0",
-    "eslint-plugin-unicorn": "39.0.0",
-    "globby": "12.0.2",
+    "eslint-plugin-unicorn": "42.0.0",
+    "globby": "13.1.2",
     "js-yaml": "4.1.0",
     "markdown-it-for-inline": "0.1.1",
     "markdown-it-sub": "1.0.0",
     "markdown-it-sup": "1.0.0",
-    "markdown-it-texmath": "0.9.7",
+    "markdown-it-texmath": "1.0.0",
     "markdownlint-rule-github-internal-links": "0.1.0",
-    "markdownlint-rule-helpers": "0.15.0",
+    "markdownlint-rule-helpers": "0.16.0",
     "npm-run-all": "4.1.5",
     "strip-json-comments": "4.0.0",
     "toml": "3.0.0",
-    "ts-loader": "9.2.6",
+    "ts-loader": "9.3.0",
     "tv4": "1.3.0",
-    "typescript": "4.5.4",
-    "webpack": "5.65.0",
-    "webpack-cli": "4.9.1"
+    "typescript": "4.7.4",
+    "webpack": "5.73.0",
+    "webpack-cli": "4.10.0"
   },
   "keywords": [
     "markdown",

package/schema/.markdownlint.jsonc

@@ -58,6 +58,8 @@
   "MD010": {
     // Include code blocks
     "code_blocks": true,
+    // Fenced code languages to ignore
+    "ignore_code_languages": [],
     // Number of spaces for each hard tab
     "spaces_per_tab": 1
   },
@@ -231,7 +233,9 @@
     // List of proper names
     "names": [],
     // Include code blocks
-    "code_blocks": true
+    "code_blocks": true,
+    // Include HTML elements
+    "html_elements": true
   },
 
   // MD045/no-alt-text - Images should have alternate text (alt text)
@@ -262,5 +266,14 @@
   "MD050": {
     // Strong style should be consistent
     "style": "consistent"
-  }
+  },
+
+  // MD051/link-fragments - Link fragments should be valid
+  "MD051": true,
+
+  // MD052/reference-links-images - Reference links and images should use a label that is defined
+  "MD052": true,
+
+  // MD053/link-image-reference-definitions - Link and image reference definitions should be needed
+  "MD053": true
 }

package/schema/.markdownlint.yaml

@@ -52,6 +52,8 @@ MD009:
 MD010:
   # Include code blocks
   code_blocks: true
+  # Fenced code languages to ignore
+  ignore_code_languages: []
   # Number of spaces for each hard tab
   spaces_per_tab: 1
 
@@ -211,6 +213,8 @@ MD044:
   names: []
   # Include code blocks
   code_blocks: true
+  # Include HTML elements
+  html_elements: true
 
 # MD045/no-alt-text - Images should have alternate text (alt text)
 MD045: true
@@ -236,4 +240,13 @@ MD049:
 # MD050/strong-style - Strong style should be consistent
 MD050:
   # Strong style should be consistent
-  style: "consistent"
+  style: "consistent"
+
+# MD051/link-fragments - Link fragments should be valid
+MD051: true
+
+# MD052/reference-links-images - Reference links and images should use a label that is defined
+MD052: true
+
+# MD053/link-image-reference-definitions - Link and image reference definitions should be needed
+MD053: true