markdownlint 0.37.4 → 0.39.0

package/helpers/helpers.cjs

@@ -9,11 +9,8 @@ const { newLineRe, nextLinesRe } = require("./shared.cjs");
 module.exports.newLineRe = newLineRe;
 module.exports.nextLinesRe = nextLinesRe;
 
-// @ts-expect-error https://github.com/microsoft/TypeScript/issues/52529
 /** @typedef {import("../lib/exports.mjs").RuleOnError} RuleOnError */
-// @ts-expect-error https://github.com/microsoft/TypeScript/issues/52529
 /** @typedef {import("../lib/exports.mjs").RuleOnErrorFixInfo} RuleOnErrorFixInfo */
-// @ts-expect-error https://github.com/microsoft/TypeScript/issues/52529
 /** @typedef {import("../lib/exports.mjs").MicromarkToken} MicromarkToken */
 // eslint-disable-next-line jsdoc/valid-types
 /** @typedef {import("micromark-extension-gfm-footnote", { with: { "resolution-mode": "import" } })} */
@@ -114,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;
@@ -142,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);
@@ -180,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);
@@ -223,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, "\\$&");
 };
 
@@ -311,9 +309,9 @@ module.exports.addErrorDetailIf = addErrorDetailIf;
  * @param {RuleOnErrorFixInfo} [fixInfo] RuleOnErrorFixInfo instance.
  * @returns {void}
  */
-function addErrorContext(
-  onError, lineNumber, context, start, end, range, fixInfo) {
-  context = ellipsify(context, start, end);
+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);
 }
 module.exports.addErrorContext = addErrorContext;
@@ -358,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 =
@@ -370,17 +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 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,
@@ -392,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(
@@ -435,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 || "" ]
             );
           }
         }
@@ -449,7 +464,7 @@ function getReferenceLinkImageData(tokens) {
           const isFullOrCollapsed = (token.children.length === 2) && !token.children.some((t) => t.type === "resource");
           const [ labelText ] = micromark.getDescendantsByType(token, [ "label", "labelText" ]);
           const [ referenceString ] = micromark.getDescendantsByType(token, [ "reference", "referenceString" ]);
-          let label = labelText?.text;
+          let label = getText(labelText);
           // Identify if footnote
           if (!isShortcut && !isFullOrCollapsed) {
             const [ footnoteCallMarker, footnoteCallString ] = token.children.filter(
@@ -462,7 +477,7 @@ function getReferenceLinkImageData(tokens) {
           }
           // Track link (handle shortcuts separately due to ambiguity in "text [text] text")
           if (isShortcut || isFullOrCollapsed) {
-            addReferenceToDictionary(token, referenceString?.text || label, isShortcut);
+            addReferenceToDictionary(token, getText(referenceString) || label, isShortcut);
           }
         }
         break;
@@ -492,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) {
@@ -532,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) {
@@ -540,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,12 +2,13 @@
 
 "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 */
-// @ts-expect-error https://github.com/microsoft/TypeScript/issues/52529
 /** @typedef {import("../lib/exports.mjs").MicromarkToken} Token */
+// eslint-disable-next-line jsdoc/valid-types
+/** @typedef {import("../lib/micromark-types.d.mts", { with: { "resolution-mode": "import" } })} */
 
 /**
  * Determines if a Micromark token is within an htmlFlow type.
@@ -16,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]);
 }
 
@@ -125,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);
   }
@@ -162,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;
@@ -215,8 +220,11 @@ function getHeadingStyle(heading) {
  * @returns {string} Heading text.
  */
 function getHeadingText(heading) {
-  const headingTexts = getDescendantsByType(heading, [ [ "atxHeadingText", "setextHeadingText" ] ]);
-  return headingTexts[0]?.text.replace(/[\r\n]+/g, " ") || "";
+  return getDescendantsByType(heading, [ [ "atxHeadingText", "setextHeadingText" ] ])
+    .flatMap((descendant) => descendant.children.filter((child) => child.type !== "htmlText"))
+    .map((data) => data.text)
+    .join("")
+    .replace(newLineRe, " ");
 }
 
 /**
@@ -265,6 +273,26 @@ function getParentOfType(token, types) {
   return current;
 }
 
+const docfxTabSyntaxRe = /^#tab\//;
+
+/**
+ * Returns whether the specified Micromark token looks like a Docfx tab.
+ *
+ * @param {Token | null} heading Micromark token.
+ * @returns {boolean} True iff the token looks like a Docfx tab.
+ */
+function isDocfxTab(heading) {
+  // See https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet#tabs
+  if (heading?.type === "atxHeading") {
+    const headingTexts = getDescendantsByType(heading, [ "atxHeadingText" ]);
+    if ((headingTexts.length === 1) && (headingTexts[0].children.length === 1) && (headingTexts[0].children[0].type === "link")) {
+      const resourceDestinationStrings = filterByTypes(headingTexts[0].children[0].children, [ "resourceDestinationString" ]);
+      return (resourceDestinationStrings.length === 1) && docfxTabSyntaxRe.test(resourceDestinationStrings[0].text);
+    }
+  }
+  return false;
+}
+
 /**
  * Set containing token types that do not contain content.
  *
@@ -274,6 +302,7 @@ const nonContentTokens = new Set([
   "blockQuoteMarker",
   "blockQuotePrefix",
   "blockQuotePrefixWhitespace",
+  "gfmFootnoteDefinitionIndent",
   "lineEnding",
   "lineEndingBlank",
   "linePrefix",
@@ -296,6 +325,7 @@ module.exports = {
   getHtmlTagInfo,
   getParentOfType,
   inHtmlFlow,
+  isDocfxTab,
   isHtmlFlowComment,
   nonContentTokens
 };

package/helpers/package.json

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

package/lib/cache.mjs

@@ -3,14 +3,20 @@
 import { getReferenceLinkImageData as helpersGetReferenceLinkImageData } from "../helpers/helpers.cjs";
 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();
+/** @type {RuleParams | undefined} */
 let params = undefined;
 
 /**
  * Initializes (resets) the cache.
  *
- * @param {import("markdownlint").RuleParams} [p] Rule parameters object.
+ * @param {RuleParams} [p] Rule parameters object.
  * @returns {void}
  */
 export function initialize(p) {
@@ -18,15 +24,25 @@ export function initialize(p) {
   params = p;
 }
 
+/**
+ * Gets the cached Micromark token array (for testing).
+ *
+ * @returns {MicromarkToken[]} Micromark tokens.
+ */
+export function micromarkTokens() {
+  return params?.parsers.micromark.tokens || [];
+}
+
 /**
  * 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();
@@ -37,26 +53,28 @@ function getCached(name, getValue) {
 /**
  * Filters a list of Micromark tokens by type and caches the result.
  *
- * @param {import("markdownlint").MicromarkTokenType[]} types Types to allow.
+ * @param {MicromarkTokenType[]} types Types to allow.
  * @param {boolean} [htmlFlow] Whether to include htmlFlow content.
- * @returns {import("markdownlint").MicromarkToken[]} Filtered tokens.
+ * @returns {MicromarkToken[]} Filtered tokens.
  */
 export function filterByTypesCached(types, htmlFlow) {
+  // @ts-ignore
   return getCached(
     // eslint-disable-next-line prefer-rest-params
     JSON.stringify(arguments),
-    () => filterByTypes(params.parsers.micromark.tokens, types, htmlFlow)
+    () => filterByTypes(micromarkTokens(), 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(params.parsers.micromark.tokens)
+    () => helpersGetReferenceLinkImageData(micromarkTokens())
   );
 }