Deprecate options.resultVersion via typing, continue to support at run-time, provide format converters in markdownlint/helpers for migration.

lib/markdownlint.d.mts

@@ -431,10 +431,6 @@ export type Options = {
      * True to ignore HTML directives.
      */
     noInlineConfig?: boolean;
-    /**
-     * Results object version.
-     */
-    resultVersion?: number;
     /**
      * Strings to lint.
      */
@@ -451,7 +447,7 @@ export type Plugin = any[];
  */
 export type ToStringCallback = (ruleAliases?: boolean) => string;
 /**
- * Lint results (for resultVersion 3).
+ * Lint results.
  */
 export type LintResults = {
     [x: string]: LintError[];

lib/markdownlint.mjs

@@ -108,9 +108,15 @@ function validateRuleList(ruleList, synchronous) {
  * @returns {LintResults} New LintResults instance.
  */
 function newResults(ruleList) {
-  const lintResults = {};
-  // eslint-disable-next-line jsdoc/require-jsdoc
+  /**
+   * Returns the string representation of a LintResults instance.
+   *
+   * @param {boolean} useAlias True if rule alias should be used instead of name.
+   * @returns {string} String representation of the instance.
+   */
   function toString(useAlias) {
+    // eslint-disable-next-line consistent-this, no-invalid-this, unicorn/no-this-assignment
+    const lintResults = this;
     let ruleNameToRule = null;
     const results = [];
     const keys = Object.keys(lintResults);
@@ -161,6 +167,7 @@ function newResults(ruleList) {
     }
     return results.join("\n");
   }
+  const lintResults = {};
   Object.defineProperty(lintResults, "toString", { "value": toString });
   // @ts-ignore
   return lintResults;
@@ -515,7 +522,7 @@ function lintContent(
       "config": null
     });
     // Function to run for each rule
-    let results = [];
+    const results = [];
     /**
      * @param {Rule} rule Rule.
      * @returns {Promise<void> | null} Promise.
@@ -623,7 +630,6 @@ function lintContent(
         const information = errorInfo.information || rule.information;
         results.push({
           lineNumber,
-          "ruleName": rule.names[0],
           "ruleNames": rule.names,
           "ruleDescription": rule.description,
           "ruleInformation": information ? information.href : null,
@@ -662,46 +668,9 @@ function lintContent(
     const formatResults = () => {
       // Sort results by rule name by line number
       results.sort((a, b) => (
-        a.ruleName.localeCompare(b.ruleName) ||
+        a.ruleNames[0].localeCompare(b.ruleNames[0]) ||
         a.lineNumber - b.lineNumber
       ));
-      if (resultVersion < 3) {
-        // Remove fixInfo and multiple errors for the same rule and line number
-        const noPrevious = {
-          "ruleName": null,
-          "lineNumber": -1
-        };
-        results = results.filter((error, index, array) => {
-          delete error.fixInfo;
-          const previous = array[index - 1] || noPrevious;
-          return (
-            (error.ruleName !== previous.ruleName) ||
-            (error.lineNumber !== previous.lineNumber)
-          );
-        });
-      }
-      if (resultVersion === 0) {
-        // Return a dictionary of rule->[line numbers]
-        const dictionary = {};
-        for (const error of results) {
-          const ruleLines = dictionary[error.ruleName] || [];
-          ruleLines.push(error.lineNumber);
-          dictionary[error.ruleName] = ruleLines;
-        }
-        // @ts-ignore
-        results = dictionary;
-      } else if (resultVersion === 1) {
-        // Use ruleAlias instead of ruleNames
-        for (const error of results) {
-          error.ruleAlias = error.ruleNames[1] || error.ruleName;
-          delete error.ruleNames;
-        }
-      } else {
-        // resultVersion 2 or 3: Remove unwanted ruleName
-        for (const error of results) {
-          delete error.ruleName;
-        }
-      }
       return results;
     };
     // Run all rules
@@ -854,9 +823,8 @@ function lintInput(options, synchronous, callback) {
     options.frontMatter;
   const handleRuleFailures = !!options.handleRuleFailures;
   const noInlineConfig = !!options.noInlineConfig;
-  const resultVersion = (options.resultVersion === undefined) ?
-    3 :
-    options.resultVersion;
+  // eslint-disable-next-line dot-notation
+  const resultVersion = (options["resultVersion"] === undefined) ? 3 : options["resultVersion"];
   const markdownItFactory =
     options.markdownItFactory ||
     (() => { throw new Error("The option 'markdownItFactory' was required (due to the option 'customRules' including a rule requiring the 'markdown-it' parser), but 'markdownItFactory' was not set."); });
@@ -923,7 +891,16 @@ function lintInput(options, synchronous, callback) {
     } else if (concurrency === 0) {
       // Finish
       done = true;
-      return callback(null, results);
+      // Deprecated: Convert results to specified resultVersion
+      let convertedResults = results;
+      if (resultVersion === 0) {
+        convertedResults = helpers.convertToResultVersion0(results);
+      } else if (resultVersion === 1) {
+        convertedResults = helpers.convertToResultVersion1(results);
+      } else if (resultVersion === 2) {
+        convertedResults = helpers.convertToResultVersion2(results);
+      }
+      return callback(null, convertedResults);
     }
     return null;
   }
@@ -1506,7 +1483,6 @@ export function getVersion() {
  * @property {boolean} [handleRuleFailures] True to catch exceptions.
  * @property {MarkdownItFactory} [markdownItFactory] Function to create a markdown-it parser.
  * @property {boolean} [noInlineConfig] True to ignore HTML directives.
- * @property {number} [resultVersion] Results object version.
  * @property {Object.<string, string>} [strings] Strings to lint.
  */
 
@@ -1525,7 +1501,7 @@ export function getVersion() {
  */
 
 /**
- * Lint results (for resultVersion 3).
+ * Lint results.
  *
  * @typedef {Object.<string, LintError[]>} LintResults
  * @property {ToStringCallback} toString String representation.