From a56441003ec146daa7e4cb1db69b00f99cb98acd Mon Sep 17 00:00:00 2001
From: David Anson <david@dlaa.me>
Date: Tue, 26 Aug 2025 00:11:40 -0700
Subject: [PATCH] wip

---
 README.md                                     |  21 +----
 helpers/helpers.cjs                           |  72 ++++++++++++++++++
 lib/markdownlint.d.mts                        |   2 +-
 lib/markdownlint.mjs                          |  44 ++---------
 .../markdownlint-test-exports.mjs.md          |   3 +
 .../markdownlint-test-exports.mjs.snap        | Bin 1504 -> 1544 bytes
 6 files changed, 84 insertions(+), 58 deletions(-)

diff --git a/README.md b/README.md
index 9a415fd5..63f43c14 100644
--- a/README.md
+++ b/README.md
@@ -622,26 +622,7 @@ comments.
 
 ##### options.resultVersion
 
-Type: `Number`
-
-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.
+DEPRECATED
 
 ##### options.strings
 
diff --git a/helpers/helpers.cjs b/helpers/helpers.cjs
index 11821eef..81a6a854 100644
--- a/helpers/helpers.cjs
+++ b/helpers/helpers.cjs
@@ -538,3 +538,75 @@ function expandTildePath(file, os) {
   return homedir ? file.replace(/^~($|\/|\\)/, `${homedir}$1`) : file;
 }
 module.exports.expandTildePath = expandTildePath;
+
+/** @typedef {import("../lib/markdownlint.mjs").LintError[]} LintErrors */
+
+/**
+ * Converts lint errors from resultVersion 3 to 2.
+ *
+ * @param {LintErrors} results Lint errors (v3).
+ * @returns {LintErrors} Lint errors (v2).
+ */
+function convertResultVersion3To2(results) {
+  // Remove fixInfo and multiple errors for the same rule and line number
+  const noPrevious = {
+    "ruleNames": [],
+    "lineNumber": -1
+  };
+  return results.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} results Lint errors (v2).
+ * @returns {LintErrors} Lint errors (v1).
+ */
+function convertResultVersion2To1(results) {
+  for (const error of results) {
+    // @ts-ignore
+    error.ruleName = error.ruleNames[0];
+    // @ts-ignore
+    error.ruleAlias = error.ruleNames[1] || error.ruleName;
+    // @ts-ignore
+    delete error.ruleNames;
+  }
+  return results;
+};
+
+/**
+ * Converts lint errors from resultVersion 2 to 0.
+ *
+ * @param {LintErrors} results Lint errors (v2).
+ * @returns {LintErrors} Lint errors (v0).
+ */
+function convertResultVersion2To0(results) {
+  const dictionary = {};
+  for (const error of results) {
+    const ruleName = error.ruleNames[0];
+    const ruleLines = dictionary[ruleName] || [];
+    ruleLines.push(error.lineNumber);
+    dictionary[ruleName] = ruleLines;
+  }
+  // @ts-ignore
+  return dictionary;
+};
+
+module.exports.convertToResultVersion0 = function convertToResultVersion0(results) {
+  return convertResultVersion2To0(convertResultVersion3To2(results));
+};
+
+module.exports.convertToResultVersion1 = function convertToResultVersion1(results) {
+  return convertResultVersion2To1(convertResultVersion3To2(results));
+};
+
+module.exports.convertToResultVersion2 = function convertToResultVersion2(results) {
+  return convertResultVersion3To2(results);
+};
diff --git a/lib/markdownlint.d.mts b/lib/markdownlint.d.mts
index d720a3f9..b0bd3dc9 100644
--- a/lib/markdownlint.d.mts
+++ b/lib/markdownlint.d.mts
@@ -451,7 +451,7 @@ export type Plugin = any[];
  */
 export type ToStringCallback = (ruleAliases?: boolean) => string;
 /**
- * Lint results (for resultVersion 3).
+ * Lint results.
  */
 export type LintResults = {
     [x: string]: LintError[];
diff --git a/lib/markdownlint.mjs b/lib/markdownlint.mjs
index e796f074..1e9b1db4 100644
--- a/lib/markdownlint.mjs
+++ b/lib/markdownlint.mjs
@@ -623,7 +623,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,45 +661,16 @@ 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)
-          );
-        });
-      }
+      // Deprecated: Convert results to specified resultVersion
       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;
+        results = helpers.convertToResultVersion0(results);
       } 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;
-        }
+        results = helpers.convertToResultVersion1(results);
+      } else if (resultVersion === 2) {
+        results = helpers.convertToResultVersion2(results);
       }
       return results;
     };
@@ -1525,7 +1495,7 @@ export function getVersion() {
  */
 
 /**
- * Lint results (for resultVersion 3).
+ * Lint results.
  *
  * @typedef {Object.<string, LintError[]>} LintResults
  * @property {ToStringCallback} toString String representation.
diff --git a/test/snapshots/markdownlint-test-exports.mjs.md b/test/snapshots/markdownlint-test-exports.mjs.md
index 1f86f881..f03e1f08 100644
--- a/test/snapshots/markdownlint-test-exports.mjs.md
+++ b/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',
diff --git a/test/snapshots/markdownlint-test-exports.mjs.snap b/test/snapshots/markdownlint-test-exports.mjs.snap
index a21e64a2950fbd37e16f75a9332d0ebc98e846f9..bf686f39cc606c40a1d48aa09feaf53c82875be7 100644
GIT binary patch
literal 1544
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

literal 1504
zcmV<61t0oBRzV<BZeeh9Xm4~Nb~6eC02}~$Gy&#|GDSf;U#SqZ#$8axfx#8S4b$GF
zi8b;%7axlV00000000A}m&=PBMI6V!z0>pPp2zNHH!*9B3Z4X;MB|ensL4iy=3!ig
zAR;x>znQ6|rn;@FF}tTIBKil2f}mm!qIed?*Ci)GJgA6z5dwk;f`|tXK}`2<*YqP1
ziF0cD`>Cq$uj=>vRnObQzK8~=_4DV*a3e_4dK@W3;f<0_NOLV&tjCej&%Ygp%&?Qa
zwHlg8eoo8rj{;Z&pa8rI;8Oq>0Qe5D-vP!B@QMR0IgLf9ajbue2F7vh<HEuMoGu&>
zPS0^ZyaX>hH8}M}r!!&dbQqnHf=iRCzvR?yd36ud8*-2`i*qw(xxkD`#H4gey>mq>
zR?&oON~v#h)Q$qB&4!>oOo)`bnB#7^3^(8^(o7mI1WyOtTbm8ob(sONB4aqI6#hI1
zUwau?kznf-rfkifv5Q4E-Jq6Jzr_V^bAg9lVB`WXxLapazh5b~;ml=E^Yin`fZ911
zc-I9!D}l8Vc>ND9@RJMt<pL{pV1FHWvJSjh2i~s(U(|u0>%iZ2V5I@v*8oNh;N=GJ
zUIX~50sPhg7Ms95O(49KWY0B$cbdTYCUBt%Tx<e6TEN~G@L&t*w~D6Rk}3CW3wW^w
zoNECemEd|g)NfnBk1gPj64)q#UfTl}J>X^!c)$ZrdO+*}FL}V59`J!zoS<2nVC72>
z_}T-0^?(H*xZ4Mw@`1BH@Rkpp_kjyOaM1@=+Q6M{;A9&(+Xmif1Lxbo?`>eY1MKer
zyaT*;>G_im@LdP^vr{zCDjD$SyTJA?5Oje<U7+6u&US&<yTHd?;QKD{cegl+SKhDP
zJ>aGuaCff=`UTL3<HG4+$(ggs*<x`lHV*OiEx~az#m^MdnKoy&5t%1QX&%W;t7TeO
zk&eW(bR-I=g3?vz%B#AYt)#r7A{HKq<dBcjVY{nl!*ErpNL7Z;XUc&{8d^6M#|s&7
zkPPGE@UY^$$AmaOl>;+nCKs2R={t-1(df}B={#Atjcg!@sfWx&9Ec_pl4dREsA1dc
zKtz%b57YC>)TZ5wE%k9FGOd+q&5(v{D(sYACU_(Sk2N3K`TR`UPBJ_;e1uDSkS5V7
zejp0z1Z7yeiY4|}rQv2{hIQ<AlOC{`4n^t&jaJv=4Cu~)^_a<Ujf;?uGc(SBUIr`;
zRV2+3W(=u^m|jaRybPMRsg#3eE*9+7Ga{4Nyx$nb`%{w(XwhC5BQnPo4M`~qleku8
z$mJ;Gwq@MPh|GxuBRQZ)xIBG$!bWtE8J3|-_GrdTAA6RRU^eb$d-Oc%^0amCj~S-S
z%+&UbYIFU7VDfb0Clhzrpt)Y1#Af3$qjE;Cu{FT;(dnd5wgz_Ql+CL=Q&w_HakgtS
zrOtIO!*<z3l5{39H}ig-^)6}MB$__4S=_a9m3C;|khFzds?<X1&t0kXD;=Xb*xb^}
ze6wQk;k2$|SjkEK$icmP_f@(>`ug@tQ%GOmRp|i9>wSAGC7-^wb2kgG???mK`JV$=
z?k5?f1E!*>41-~kx79|yqezX3CE2el;Vl(8!L`wqU>62aNSiAK=_gMm?jB9zG1FWZ
zb-MxEwhRP1sf<9-&{TG#J7aQF*yh(7tD<7NUpuM1K#&~G`i-9xwF$Tkb9-sK-eM{y
zpJ}859kW5T<1Nc5*xIA?EB%>iWGrRdUPng3n5i%@tZ(<Pm!D(8wN8UeRtcD~_pWVv
zyDHQ`M4G}pJZpgoJQaq=g0}osTHy9PQ(4z`!0W15HPWSjp{q8R^EQoQT-czjP1_W`
zNCdH>;p|hyw#1G$Dk^7$?TFq~*n{=cKQRBd2l!{k+)yDAYK1I&x|n6|<*bxTLq@^o
z<q(X`L{v&6Nu54Z6ik)Sm7-Wqt1b-E3KUF^rfgKLjqZ>uZGz23ZoSG+uYUj+xW}=F
G4gdhEj^oMz