improvement(eslint-plugin-fluid): Implement auto-fix for no-hyphen-after-jsdoc-tag rule and give better range info (#25935)

Now reports the text range containing the hyphen character and
surrounding whitespace, rather than the range containing the TSDoc tag.
Also implements auto-fix behavior (replacing hyphen character and
surrounding whitespace with a single space).

Author: Josmithr

common/build/eslint-plugin-fluid/src/rules/no-hyphen-after-jsdoc-tag.js

@@ -8,23 +8,47 @@
  * @typedef {import("eslint").Rule.RuleModule} RuleModule
  * @typedef {import('@microsoft/tsdoc').DocNode} DocNode
  * @typedef {import('@microsoft/tsdoc').DocPlainText} DocPlainText
+ *
+ * @typedef {{
+ * 	startIndex: number; // Starting character index of the hyphen pattern (inclusive).
+ * 	endIndex: number; // Ending character index of the hyphen pattern (exclusive).
+ * }} HyphenPatternMatch
  */
 
+const { fail } = require("node:assert");
 const { DocNodeKind, TSDocParser } = require("@microsoft/tsdoc");
 
 const parser = new TSDocParser();
 
 /**
  * Checks if a comment text starts with a hyphen.
  * @param {DocPlainText} plainTextNode - The plain text node to check.
+ * @return {HyphenPatternMatch | undefined} The hyphen pattern match info if found; otherwise, undefined.
  */
 function doesTextNodeStartWithHyphen(plainTextNode) {
-	return plainTextNode.text.trimStart().startsWith("-");
+	// RegEx explanation:
+	// ^\s*    - Match the start of the string, followed by zero or more whitespace characters
+	// -       - Match the `-` character literal
+	// \s*     - Match zero or more whitespace characters
+	const match = plainTextNode.text.match(/^\s*-\s*/);
+
+	if (!match) {
+		return undefined;
+	}
+
+	const textRange =
+		plainTextNode.textExcerpt?.getContainingTextRange() ??
+		fail("Expected textExcerpt to be defined.");
+	return {
+		startIndex: textRange.pos,
+		endIndex: textRange.pos + match[0].length,
+	};
 }
 
 /**
  * Checks if a comment body starts with a hyphen.
  * @param { DocNode } commentBodyNode - The doc node representing the body of the comment.
+ * @return {HyphenPatternMatch | undefined} The hyphen pattern match info if found; otherwise, undefined.
  */
 function doesCommentBodyStartWithHyphen(commentBodyNode) {
 	// Walk down first node of the tree until we find a leaf.
@@ -36,7 +60,7 @@ function doesCommentBodyStartWithHyphen(commentBodyNode) {
 
 	const childNodes = commentBodyNode.getChildNodes();
 	if (childNodes.length === 0) {
-		return false;
+		return undefined;
 	}
 
 	return doesCommentBodyStartWithHyphen(childNodes[0]);
@@ -58,6 +82,7 @@ const rule = {
 			hyphenAfterTag:
 				"JSDoc/TSDoc block tags must not be followed by a hyphen character (`-`).",
 		},
+		fixable: "code",
 		schema: [],
 	},
 
@@ -101,25 +126,20 @@ const rule = {
 					// Note: the TSDoc format makes it difficult to extract the range information for the block content specifically.
 					// Instead, we just report the range for the tag itself.
 					for (const block of blocksToCheck) {
-						if (doesCommentBodyStartWithHyphen(block.content)) {
-							const tagTextRange = block.blockTag
-								.getTokenSequence()
-								.getContainingTextRange();
-							const tagTextRangeStart = tagTextRange.pos - 1; // Include the `@`
-							const tagTextRangeEnd = tagTextRange.end;
-							const startIndex = sourceCode.getLocFromIndex(
-								commentStartIndex + tagTextRangeStart,
-							);
-							const endIndex = sourceCode.getLocFromIndex(
-								commentStartIndex + tagTextRangeEnd,
-							);
+						const hyphenMatch = doesCommentBodyStartWithHyphen(block.content);
+						if (hyphenMatch) {
+							const startIndex = commentStartIndex + hyphenMatch.startIndex - 1;
+							const endIndex = commentStartIndex + hyphenMatch.endIndex - 1;
 
 							context.report({
 								loc: {
-									start: startIndex,
-									end: endIndex,
+									start: sourceCode.getLocFromIndex(startIndex),
+									end: sourceCode.getLocFromIndex(endIndex),
 								},
 								messageId: "hyphenAfterTag",
+								fix(fixer) {
+									return fixer.replaceTextRange([startIndex, endIndex], " ");
+								},
 							});
 						}
 					}

common/build/eslint-plugin-fluid/src/test/no-hyphen-after-jsdoc-tag.test.js

@@ -38,21 +38,30 @@ describe(`Do not allow \`-\` following JSDoc/TSDoc tags (eslint ${eslintVersion}
 		const error1 = result.messages[0];
 		assert.strictEqual(error1.message, expectedErrorMessage);
 		assert.strictEqual(error1.line, 8);
-		assert.strictEqual(error1.column, 4); // 1-based, inclusive
-		assert.strictEqual(error1.endColumn, 13); // 1-based, exclusive
+		assert.strictEqual(error1.column, 12); // 1-based, inclusive
+		assert.strictEqual(error1.endColumn, 15); // 1-based, exclusive
+		assert.notEqual(error1.fix, undefined);
+		assert.deepEqual(error1.fix.range, [234, 237]); // 0-based global character index in the file. The start is inclusive, and the end is exclusive.
+		assert.deepEqual(error1.fix.text, " "); // Replace hyphen and surrounding whitespace with a single space.
 
 		// Error 2
 		const error2 = result.messages[1];
 		assert.strictEqual(error2.message, expectedErrorMessage);
 		assert.strictEqual(error2.line, 9);
-		assert.strictEqual(error2.column, 4); // 1-based, inclusive
-		assert.strictEqual(error2.endColumn, 16); // 1-based, exclusive
+		assert.strictEqual(error2.column, 15); // 1-based, inclusive
+		assert.strictEqual(error2.endColumn, 19); // 1-based, exclusive
+		assert.notEqual(error2.fix, undefined);
+		assert.deepEqual(error2.fix.range, [274, 278]); // 0-based global character index in the file. The start is inclusive, and the end is exclusive.
+		assert.deepEqual(error2.fix.text, " "); // Replace hyphen and surrounding whitespace with a single space.
 
 		// Error 3
 		const error3 = result.messages[2];
 		assert.strictEqual(error3.message, expectedErrorMessage);
 		assert.strictEqual(error3.line, 10);
-		assert.strictEqual(error3.column, 4); // 1-based, inclusive
-		assert.strictEqual(error3.endColumn, 13); // 1-based, exclusive
+		assert.strictEqual(error3.column, 12); // 1-based, inclusive
+		assert.strictEqual(error3.endColumn, 16); // 1-based, exclusive
+		assert.notEqual(error3.fix, undefined);
+		assert.deepEqual(error3.fix.range, [338, 342]); // 0-based global character index in the file. The start is inclusive, and the end is exclusive.
+		assert.deepEqual(error3.fix.text, " "); // Replace hyphen and surrounding whitespace with a single space.
 	});
 });

common/build/eslint-plugin-fluid/src/test/test-cases/no-hyphen-after-jsdoc-tag/test.ts

@@ -6,8 +6,8 @@
 /**
  * I am a test function with pretty standard docs, but all of my tags have hyphens after them :(
  * @remarks - Here are some remarks.
- * @deprecated - This function is deprecated, use something else.
- * @returns - The concatenated string.
+ * @deprecated -  This function is deprecated, use something else.
+ * @returns  -	The concatenated string.
  */
 function invalid<T>(param1: string, param2: T): string {
 	return `${param1} - ${param2}`;