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

README.md

@@ -620,28 +620,15 @@ By default, properly-formatted inline comments can be used to create exceptions
 for parts of a document. Setting `noInlineConfig` to `true` ignores all such
 comments.
 
-##### options.resultVersion
+##### ~~options.resultVersion~~
 
-Type: `Number`
+This property is *deprecated* and should be removed. The default format of the
+`result` object remains the same as setting `resultVersion` to `3`. For
+continued access to other (previously *deprecated*) formats:
 
-Specifies which version of the `result` object to return (see the "Usage"
-section below for examples).
-
-Passing a `resultVersion` of `0` corresponds to the original, simple format
-where each error is identified by rule name and line number. *Deprecated*
-
-Passing a `resultVersion` of `1` corresponds to a detailed format where each
-error includes information about the line number, rule name, alias, description,
-as well as any additional detail or context that is available. *Deprecated*
-
-Passing a `resultVersion` of `2` corresponds to a detailed format where each
-error includes information about the line number, rule names, description, as
-well as any additional detail or context that is available. *Deprecated*
-
-Passing a `resultVersion` of `3` corresponds to the detailed version `2` format
-with additional information about how to fix automatically-fixable errors. In
-this mode, all errors that occur on each line are reported (other versions
-report only the first error for each rule). This is the default behavior.
+```javascript
+import { convertToResultVersion0, convertToResultVersion1, convertToResultVersion2 } from "markdownlint/helpers";
+```
 
 ##### options.strings
 

helpers/helpers.cjs

@@ -538,3 +538,111 @@ 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) => {
+    delete error.fixInfo;
+    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) {
+  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 {(LintErrors) => LintErrors} transform Lint errors (v?).
+ * @returns {LintResults} Lint results (v?).
+ */
+function copyAndTransformResults(results, transform) {
+  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);
+};

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.

test/markdownlint-test-custom-rules.mjs

@@ -24,6 +24,7 @@ test("customRulesV0", (t) => new Promise((resolve) => {
     "customRules": customRules.all,
     "files": [ customRulesMd ],
     markdownItFactory,
+    // @ts-ignore
     "resultVersion": 0
   };
   lintAsync(options, function callback(err, actualResult) {
@@ -97,6 +98,7 @@ test("customRulesV1", (t) => new Promise((resolve) => {
     "customRules": customRules.all,
     "files": [ customRulesMd ],
     markdownItFactory,
+    // @ts-ignore
     "resultVersion": 1
   };
   lintAsync(options, function callback(err, actualResult) {
@@ -229,6 +231,7 @@ test("customRulesV2", (t) => new Promise((resolve) => {
     "customRules": customRules.all,
     "files": [ customRulesMd ],
     markdownItFactory,
+    // @ts-ignore
     "resultVersion": 2
   };
   lintAsync(options, function callback(err, actualResult) {
@@ -358,6 +361,7 @@ test("customRulesConfig", (t) => new Promise((resolve) => {
       "letters-e-x": false
     },
     markdownItFactory,
+    // @ts-ignore
     "resultVersion": 0
   };
   lintAsync(options, function callback(err, actualResult) {
@@ -387,6 +391,7 @@ test("customRulesNpmPackage", (t) => new Promise((resolve) => {
     "strings": {
       "string": "# Text\n\n---\n\nText ✅\n"
     },
+    // @ts-ignore
     "resultVersion": 0
   };
   lintAsync(options, function callback(err, actualResult) {

test/markdownlint-test-result-object.mjs

@@ -2,7 +2,9 @@
 
 import test from "ava";
 import { lint as lintAsync } from "markdownlint/async";
+import { lint as lintPromise } from "markdownlint/promise";
 import { lint as lintSync } from "markdownlint/sync";
+import { convertToResultVersion0, convertToResultVersion1, convertToResultVersion2 } from "markdownlint/helpers";
 import { importWithTypeJson } from "./esm-helpers.mjs";
 const packageJson = await importWithTypeJson(import.meta, "../package.json");
 const { homepage, version } = packageJson;
@@ -623,3 +625,40 @@ test("frontMatterResultVersion3", (t) => new Promise((resolve) => {
     resolve();
   });
 }));
+
+test("convertToResultVersionN", async(t) => {
+  t.plan(8);
+  const options = {
+    "files": [
+      "./test/break-all-the-rules.md",
+      "./test/inline-disable-enable.md"
+    ],
+    "strings": {
+      "first": "#  Heading",
+      "second": "## Heading"
+    }
+  };
+  const [ base, version3, version2, version1, version0 ] = await Promise.all([
+    lintPromise(options),
+    // @ts-ignore
+    lintPromise({ ...options, "resultVersion": 3 }),
+    // @ts-ignore
+    lintPromise({ ...options, "resultVersion": 2 }),
+    // @ts-ignore
+    lintPromise({ ...options, "resultVersion": 1 }),
+    // @ts-ignore
+    lintPromise({ ...options, "resultVersion": 0 })
+  ]);
+  const v3 = version3;
+  t.deepEqual(v3, base);
+  t.is(v3.toString(), base.toString());
+  const v2 = convertToResultVersion2(base);
+  t.deepEqual(v2, version2);
+  t.is(v2.toString(), version2.toString());
+  const v1 = convertToResultVersion1(base);
+  t.deepEqual(v1, version1);
+  t.is(v1.toString(), version1.toString());
+  const v0 = convertToResultVersion0(base);
+  t.deepEqual(v0, version0);
+  t.is(v0.toString(), version0.toString());
+});

test/markdownlint-test.mjs

@@ -546,6 +546,7 @@ test("nullFrontMatter", (t) => new Promise((resolve) => {
       "default": false,
       "MD010": true
     },
+    // @ts-ignore
     "resultVersion": 0
   }, function callback(err, result) {
     t.falsy(err);
@@ -598,6 +599,7 @@ test("noInlineConfig", (t) => new Promise((resolve) => {
       ].join("\n")
     },
     "noInlineConfig": true,
+    // @ts-ignore
     "resultVersion": 0
   }, function callback(err, result) {
     t.falsy(err);
@@ -646,7 +648,7 @@ test("readmeHeadings", (t) => new Promise((resolve) => {
           "##### options.handleRuleFailures",
           "##### options.markdownItFactory",
           "##### options.noInlineConfig",
-          "##### options.resultVersion",
+          "##### ~~options.resultVersion~~",
           "##### options.strings",
           "#### callback",
           "#### result",
@@ -1229,6 +1231,7 @@ Text with: [^footnote]
 [reference]: https://example.com
 `
     },
+    // @ts-ignore
     "resultVersion": 0
   }, (err, actual) => {
     t.falsy(err);

test/snapshots/markdownlint-test-exports.mjs.md

@@ -28,6 +28,9 @@ Generated by [AVA](https://avajs.dev).
         'clearHtmlCommentText',
         'cloneIfArray',
         'cloneIfUrl',
+        'convertToResultVersion0',
+        'convertToResultVersion1',
+        'convertToResultVersion2',
         'default',
         'ellipsify',
         'endOfLineGemojiCodeRe',