markdownlint 0.38.0 → 0.39.0

package/doc/md059.md

@@ -27,4 +27,7 @@ translations for every language.
 
 Note: This rule checks Markdown links; HTML links are ignored.
 
-More information: <https://webaim.org/techniques/hypertext/>
+More information:
+
+- <https://webaim.org/techniques/hypertext/>
+- <https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-link-only.html>

package/doc/md060.md

@@ -0,0 +1,70 @@
+# `MD060` - Table column style
+
+Tags: `table`
+
+Aliases: `table-column-style`
+
+Parameters:
+
+- `style`: Table column style (`string`, default `any`, values `aligned` /
+  `any` / `compact` / `tight`)
+
+This rule is triggered when the column separators of a
+[GitHub Flavored Markdown table][gfm-table-060] are used inconsistently.
+
+This rule recognizes three table column styles based on popular use:
+
+Style `aligned` looks the most like a table:
+
+```markdown
+| Character | Meaning |
+| --------- | ------- |
+| Y         | Yes     |
+| N         | No      |
+```
+
+Style `compact` uses a single space to pad cell content:
+
+```markdown
+| Character | Meaning |
+| --- | --- |
+| Y | Yes |
+| N | No |
+```
+
+Style `tight` uses no padding for cell content:
+
+```markdown
+|Character|Meaning|
+|---|---|
+|Y|Yes|
+|N|No|
+```
+
+When this rule's `style` parameter is set to `aligned`, `compact`, or `tight`,
+every table must match the corresponding pattern and errors will be reported for
+any violations. By default, or when the `any` style is used, each table is
+analyzed to see if it satisfies any supported style. If so, no errors are
+reported. If not, errors are be reported for whichever style would produce the
+*fewest* errors (i.e., whichever style is the closest match).
+
+Note: Pipe alignment for the `aligned` style is based on character count, so
+wide characters and multi-character encodings can produce unexpected results.
+The following table is correctly aligned based on character count, though some
+editors render the emoji wider:
+
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable extended-ascii -->
+
+```markdown
+| Response | Emoji |
+| -------- | ----- |
+| Yes      | ✅     |
+| No       | ❎     |
+```
+
+<!-- markdownlint-restore -->
+
+Rationale: Consistent formatting makes it easier to understand a document.
+
+[gfm-table-060]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables

package/helpers/README.md

@@ -22,8 +22,8 @@ be useful to custom rule authors and may avoid duplicating code.
 *None* - The entire body of code is tested to 100% coverage by the core
 `markdownlint` project, so there are no additional tests here.
 
-[custom-rules]: https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/CustomRules.md
+[custom-rules]: https://github.com/DavidAnson/markdownlint/blob/v0.39.0/doc/CustomRules.md
 [jsdoc]: https://en.m.wikipedia.org/wiki/JSDoc
 [markdown]: https://en.wikipedia.org/wiki/Markdown
 [markdownlint]: https://github.com/DavidAnson/markdownlint
-[rules]: https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/Rules.md
+[rules]: https://github.com/DavidAnson/markdownlint/blob/v0.39.0/doc/Rules.md

package/helpers/helpers.cjs

@@ -111,10 +111,11 @@ module.exports.cloneIfArray = cloneIfArray;
 /**
  * Clones the input if it is a URL.
  *
- * @param {Object} url Object of unknown type.
+ * @param {Object | undefined} url Object of unknown type.
  * @returns {Object} Clone of obj iff obj is a URL.
  */
 function cloneIfUrl(url) {
+  // @ts-ignore
   return isUrl(url) ? new URL(url) : url;
 }
 module.exports.cloneIfUrl = cloneIfUrl;
@@ -139,7 +140,7 @@ module.exports.getHtmlAttributeRe = function getHtmlAttributeRe(name) {
 function isBlankLine(line) {
   const startComment = "<!--";
   const endComment = "-->";
-  const removeComments = (s) => {
+  const removeComments = (/** @type {string} */ s) => {
     while (true) {
       const start = s.indexOf(startComment);
       const end = s.indexOf(endComment);
@@ -177,8 +178,8 @@ const startsWithPipeRe = /^ *\|/;
 const notCrLfRe = /[^\r\n]/g;
 const notSpaceCrLfRe = /[^ \r\n]/g;
 const trailingSpaceRe = / +[\r\n]/g;
-const replaceTrailingSpace = (s) => s.replace(notCrLfRe, safeCommentCharacter);
-module.exports.clearHtmlCommentText = function clearHtmlCommentText(text) {
+const replaceTrailingSpace = (/** @type {string} */ s) => s.replace(notCrLfRe, safeCommentCharacter);
+module.exports.clearHtmlCommentText = function clearHtmlCommentText(/** @type {string} */ text) {
   let i = 0;
   while ((i = text.indexOf(htmlCommentBegin, i)) !== -1) {
     const j = text.indexOf(htmlCommentEnd, i + 2);
@@ -220,7 +221,7 @@ module.exports.clearHtmlCommentText = function clearHtmlCommentText(text) {
 };
 
 // Escapes a string for use in a RegExp
-module.exports.escapeForRegExp = function escapeForRegExp(str) {
+module.exports.escapeForRegExp = function escapeForRegExp(/** @type {string} */ str) {
   return str.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
 };
 
@@ -308,8 +309,8 @@ module.exports.addErrorDetailIf = addErrorDetailIf;
  * @param {RuleOnErrorFixInfo} [fixInfo] RuleOnErrorFixInfo instance.
  * @returns {void}
  */
-function addErrorContext(
-  onError, lineNumber, context, start, end, range, fixInfo) {
+function addErrorContext(onError, lineNumber, context, start, end, range, fixInfo) {
+  // Normalize new line characters so Linux and Windows trim consistently
   context = ellipsify(context.replace(newLineRe, "\n"), start, end);
   addError(onError, lineNumber, undefined, context, range, fixInfo);
 }
@@ -355,7 +356,7 @@ module.exports.hasOverlap = function hasOverlap(rangeA, rangeB) {
 
 // Determines if the front matter includes a title
 module.exports.frontMatterHasTitle =
-  function frontMatterHasTitle(frontMatterLines, frontMatterTitlePattern) {
+  function frontMatterHasTitle(/** @type {readonly string[]} */ frontMatterLines, /** @type {string} */ frontMatterTitlePattern) {
     const ignoreFrontMatter =
       (frontMatterTitlePattern !== undefined) && !frontMatterTitlePattern;
     const frontMatterTitleRe =
@@ -367,18 +368,31 @@ module.exports.frontMatterHasTitle =
       frontMatterLines.some((line) => frontMatterTitleRe.test(line));
   };
 
+/**
+ * Result object for getReferenceLinkImageData.
+ *
+ * @typedef {Object} GetReferenceLinkImageDataResult
+ * @property {Map<string, number[][]>} references References.
+ * @property {Map<string, number[][]>} shortcuts Shortcuts.
+ * @property {Map<string, [number, string]>} definitions Definitions.
+ * @property {[string, number][]} duplicateDefinitions Duplicate definitions.
+ * @property {number[]} definitionLineIndices Definition line indices.
+ */
+
 /**
  * Returns an object with information about reference links and images.
  *
  * @param {MicromarkToken[]} tokens Micromark tokens.
- * @returns {Object} Reference link/image data.
+ * @returns {GetReferenceLinkImageDataResult} Reference link/image data.
  */
 function getReferenceLinkImageData(tokens) {
-  const normalizeReference = (s) => s.toLowerCase().trim().replace(/\s+/g, " ");
-  const getText = (t) => t?.children.filter((c) => c.type !== "blockQuotePrefix").map((c) => c.text).join("");
+  const normalizeReference = (/** @type {string} */ s) => s.toLowerCase().trim().replace(/\s+/g, " ");
+  const getText = (/** @type {MicromarkToken} */ t) => t?.children.filter((c) => c.type !== "blockQuotePrefix").map((c) => c.text).join("");
+  /** @type {Map<string, number[][]>} */
   const references = new Map();
+  /** @type {Map<string, number[][]>} */
   const shortcuts = new Map();
-  const addReferenceToDictionary = (token, label, isShortcut) => {
+  const addReferenceToDictionary = (/** @type {MicromarkToken} */ token, /** @type {string} */ label, /** @type {boolean} */ isShortcut) => {
     const referenceDatum = [
       token.startLine - 1,
       token.startColumn - 1,
@@ -390,8 +404,11 @@ function getReferenceLinkImageData(tokens) {
     referenceData.push(referenceDatum);
     dictionary.set(reference, referenceData);
   };
+  /** @type {Map<string, [number, string]>} */
   const definitions = new Map();
+  /** @type {number[]} */
   const definitionLineIndices = [];
+  /** @type {[string, number][]} */
   const duplicateDefinitions = [];
   const filteredTokens =
     micromark.filterByTypes(
@@ -433,7 +450,7 @@ function getReferenceLinkImageData(tokens) {
               micromark.getDescendantsByType(parent, [ "definitionDestination", "definitionDestinationRaw", "definitionDestinationString" ])[0]?.text;
             definitions.set(
               reference,
-              [ token.startLine - 1, destinationString ]
+              [ token.startLine - 1, destinationString || "" ]
             );
           }
         }
@@ -490,7 +507,7 @@ module.exports.getReferenceLinkImageData = getReferenceLinkImageData;
  * Gets the most common line ending, falling back to the platform default.
  *
  * @param {string} input Markdown content to analyze.
- * @param {Object} [os] Node.js "os" module.
+ * @param {{EOL: string}} [os] Node.js "os" module.
  * @returns {string} Preferred line ending.
  */
 function getPreferredLineEnding(input, os) {
@@ -530,7 +547,7 @@ module.exports.getPreferredLineEnding = getPreferredLineEnding;
  * Expands a path with a tilde to an absolute path.
  *
  * @param {string} file Path that may begin with a tilde.
- * @param {Object} os Node.js "os" module.
+ * @param {{homedir: () => string}} os Node.js "os" module.
  * @returns {string} Absolute path (or original path).
  */
 function expandTildePath(file, os) {
@@ -538,3 +555,142 @@ function expandTildePath(file, os) {
   return homedir ? file.replace(/^~($|\/|\\)/, `${homedir}$1`) : file;
 }
 module.exports.expandTildePath = expandTildePath;
+
+/** @typedef {import("../lib/markdownlint.mjs").LintError[]} LintErrors */
+/** @typedef {import("../lib/markdownlint.mjs").LintResults} LintResults */
+
+/**
+ * Converts lint errors from resultVersion 3 to 2.
+ *
+ * @param {LintErrors} errors Lint errors (v3).
+ * @returns {LintErrors} Lint errors (v2).
+ */
+function convertLintErrorsVersion3To2(errors) {
+  const noPrevious = {
+    "ruleNames": [],
+    "lineNumber": -1
+  };
+  return errors.filter((error, index, array) => {
+    // @ts-ignore
+    delete error.fixInfo;
+    // @ts-ignore
+    delete error.severity;
+    const previous = array[index - 1] || noPrevious;
+    return (
+      (error.ruleNames[0] !== previous.ruleNames[0]) ||
+      (error.lineNumber !== previous.lineNumber)
+    );
+  });
+}
+
+/**
+ * Converts lint errors from resultVersion 2 to 1.
+ *
+ * @param {LintErrors} errors Lint errors (v2).
+ * @returns {LintErrors} Lint errors (v1).
+ */
+function convertLintErrorsVersion2To1(errors) {
+  for (const error of errors) {
+    // @ts-ignore
+    error.ruleName = error.ruleNames[0];
+    // @ts-ignore
+    error.ruleAlias = error.ruleNames[1] || error.ruleName;
+    // @ts-ignore
+    delete error.ruleNames;
+  }
+  return errors;
+}
+
+/**
+ * Converts lint errors from resultVersion 2 to 0.
+ *
+ * @param {LintErrors} errors Lint errors (v2).
+ * @returns {LintErrors} Lint errors (v0).
+ */
+function convertLintErrorsVersion2To0(errors) {
+  /** @type {Object.<string, number[]>} */
+  const dictionary = {};
+  for (const error of errors) {
+    const ruleName = error.ruleNames[0];
+    const ruleLines = dictionary[ruleName] || [];
+    ruleLines.push(error.lineNumber);
+    dictionary[ruleName] = ruleLines;
+  }
+  // @ts-ignore
+  return dictionary;
+}
+
+/**
+ * Copies and transforms lint results from resultVersion 3 to ?.
+ *
+ * @param {LintResults} results Lint results (v3).
+ * @param {(errors: LintErrors) => LintErrors} transform Lint errors (v?).
+ * @returns {LintResults} Lint results (v?).
+ */
+function copyAndTransformResults(results, transform) {
+  /** @type {Object.<string, LintErrors>} */
+  const newResults = {};
+  Object.defineProperty(newResults, "toString", { "value": results.toString });
+  for (const key of Object.keys(results)) {
+    const arr = results[key].map((r) => ({ ...r }));
+    newResults[key] = transform(arr);
+  }
+  // @ts-ignore
+  return newResults;
+}
+
+/**
+ * Converts lint results from resultVersion 3 to 0.
+ *
+ * @param {LintResults} results Lint results (v3).
+ * @returns {LintResults} Lint results (v0).
+ */
+module.exports.convertToResultVersion0 = function convertToResultVersion0(results) {
+  return copyAndTransformResults(results, (r) => convertLintErrorsVersion2To0(convertLintErrorsVersion3To2(r)));
+};
+
+/**
+ * Converts lint results from resultVersion 3 to 1.
+ *
+ * @param {LintResults} results Lint results (v3).
+ * @returns {LintResults} Lint results (v1).
+ */
+module.exports.convertToResultVersion1 = function convertToResultVersion1(results) {
+  return copyAndTransformResults(results, (r) => convertLintErrorsVersion2To1(convertLintErrorsVersion3To2(r)));
+};
+
+/**
+ * Converts lint results from resultVersion 3 to 2.
+ *
+ * @param {LintResults} results Lint results (v3).
+ * @returns {LintResults} Lint results (v2).
+ */
+module.exports.convertToResultVersion2 = function convertToResultVersion2(results) {
+  return copyAndTransformResults(results, convertLintErrorsVersion3To2);
+};
+
+/**
+ * Formats lint results to an array of strings.
+ *
+ * @param {LintResults|undefined} lintResults Lint results.
+ * @returns {string[]} Lint error strings.
+ */
+module.exports.formatLintResults = function formatLintResults(lintResults) {
+  const results = [];
+  const entries = Object.entries(lintResults || {});
+  entries.sort((a, b) => a[0].localeCompare(b[0]));
+  for (const [ source, lintErrors ] of entries) {
+    for (const lintError of lintErrors) {
+      const { lineNumber, ruleNames, ruleDescription, errorDetail, errorContext, errorRange, severity } = lintError;
+      const rule = ruleNames.join("/");
+      const line = `:${lineNumber}`;
+      const rangeStart = (errorRange && errorRange[0]) || 0;
+      const column = rangeStart ? `:${rangeStart}` : "";
+      const description = ruleDescription;
+      const detail = (errorDetail ? ` [${errorDetail}]` : "");
+      const context = (errorContext ? ` [Context: "${errorContext}"]` : "");
+      results.push(`${source}${line}${column} ${severity} ${rule} ${description}${detail}${context}`);
+    }
+  }
+  return results;
+};

package/helpers/micromark-helpers.cjs

@@ -2,7 +2,7 @@
 
 "use strict";
 
-const { flatTokensSymbol, htmlFlowSymbol } = require("./shared.cjs");
+const { flatTokensSymbol, htmlFlowSymbol, newLineRe } = require("./shared.cjs");
 
 // eslint-disable-next-line jsdoc/valid-types
 /** @typedef {import("micromark-util-types", { with: { "resolution-mode": "import" } }).TokenType} TokenType */
@@ -17,6 +17,7 @@ const { flatTokensSymbol, htmlFlowSymbol } = require("./shared.cjs");
  * @returns {boolean} True iff the token is within an htmlFlow type.
  */
 function inHtmlFlow(token) {
+  // @ts-ignore
   return Boolean(token[htmlFlowSymbol]);
 }
 
@@ -126,8 +127,11 @@ function filterByPredicate(tokens, allowed, transformChildren) {
  * @returns {Token[]} Filtered tokens.
  */
 function filterByTypes(tokens, types, htmlFlow) {
-  const predicate = (token) => types.includes(token.type) && (htmlFlow || !inHtmlFlow(token));
-  const flatTokens = tokens[flatTokensSymbol];
+  const predicate = (/** @type {Token} */ token) => types.includes(token.type) && (htmlFlow || !inHtmlFlow(token));
+  /** @type {Token[]} */
+  const flatTokens =
+    // @ts-ignore
+    tokens[flatTokensSymbol];
   if (flatTokens) {
     return flatTokens.filter(predicate);
   }
@@ -163,7 +167,7 @@ function getBlockQuotePrefixText(tokens, lineNumber, count = 1) {
 function getDescendantsByType(parent, typePath) {
   let tokens = Array.isArray(parent) ? parent : [ parent ];
   for (const type of typePath) {
-    const predicate = (token) => Array.isArray(type) ? type.includes(token.type) : (type === token.type);
+    const predicate = (/** @type {Token} */ token) => Array.isArray(type) ? type.includes(token.type) : (type === token.type);
     tokens = tokens.flatMap((t) => t.children.filter(predicate));
   }
   return tokens;
@@ -216,12 +220,11 @@ function getHeadingStyle(heading) {
  * @returns {string} Heading text.
  */
 function getHeadingText(heading) {
-  const headingText = getDescendantsByType(heading, [ [ "atxHeadingText", "setextHeadingText" ] ])
+  return getDescendantsByType(heading, [ [ "atxHeadingText", "setextHeadingText" ] ])
     .flatMap((descendant) => descendant.children.filter((child) => child.type !== "htmlText"))
     .map((data) => data.text)
     .join("")
-    .replace(/[\r\n]+/g, " ");
-  return headingText || "";
+    .replace(newLineRe, " ");
 }
 
 /**
@@ -299,6 +302,7 @@ const nonContentTokens = new Set([
   "blockQuoteMarker",
   "blockQuotePrefix",
   "blockQuotePrefixWhitespace",
+  "gfmFootnoteDefinitionIndent",
   "lineEnding",
   "lineEndingBlank",
   "linePrefix",

package/helpers/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markdownlint-rule-helpers",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "A collection of markdownlint helper functions for custom rules",
   "main": "./helpers.cjs",
   "exports": {

package/lib/cache.mjs

@@ -6,6 +6,7 @@ import { filterByTypes } from "../helpers/micromark-helpers.cjs";
 /** @typedef {import("markdownlint").RuleParams} RuleParams */
 /** @typedef {import("markdownlint").MicromarkToken} MicromarkToken */
 /** @typedef {import("markdownlint").MicromarkTokenType} MicromarkTokenType */
+/** @typedef {import("../helpers/helpers.cjs").GetReferenceLinkImageDataResult} GetReferenceLinkImageDataResult */
 
 /** @type {Map<string, object>} */
 const map = new Map();
@@ -36,11 +37,12 @@ export function micromarkTokens() {
  * Gets a cached object value - computes it and caches it.
  *
  * @param {string} name Cache object name.
- * @param {Function} getValue Getter for object value.
+ * @param {() => Object} getValue Getter for object value.
  * @returns {Object} Object value.
  */
 function getCached(name, getValue) {
   if (map.has(name)) {
+    // @ts-ignore
     return map.get(name);
   }
   const value = getValue();
@@ -56,6 +58,7 @@ function getCached(name, getValue) {
  * @returns {MicromarkToken[]} Filtered tokens.
  */
 export function filterByTypesCached(types, htmlFlow) {
+  // @ts-ignore
   return getCached(
     // eslint-disable-next-line prefer-rest-params
     JSON.stringify(arguments),
@@ -66,9 +69,10 @@ export function filterByTypesCached(types, htmlFlow) {
 /**
  * Gets a reference link and image data object.
  *
- * @returns {Object} Reference link and image data object.
+ * @returns {GetReferenceLinkImageDataResult} Reference link and image data object.
  */
 export function getReferenceLinkImageData() {
+  // @ts-ignore
   return getCached(
     getReferenceLinkImageData.name,
     () => helpersGetReferenceLinkImageData(micromarkTokens())