feat(eslint-plugin-fluid): Add a rule preventing the use of - immediately following a JSDoc/TSDoc tag (#25556)

Following a TSDoc block tag with a `-` is a commonly made mistake. Block
tags do not want a `-` between the tag and the content. This PR adds a
rule to help detect and prevent this anti-pattern.

Author: Josmithr

common/build/eslint-plugin-fluid/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @fluidframework/eslint-plugin-fluid Changelog
 
+## [0.3.0](https://github.com/microsoft/FluidFramework/releases/tag/eslint-plugin-fluid_v0.2.0)
+
+New rules added:
+
+- `@fluid-internal/fluid/no-hyphen-after-jsdoc-tag`: Forbids following a JSDoc/TSDoc comment tag with a `-`.
+    - Such syntax is commonly used by mistake, due to the fact that `TSDoc` requires a hyphen after the parameter name of a `@param` comment. But no tags want a hyphen between the tag name and the body.
+
 ## [0.2.0](https://github.com/microsoft/FluidFramework/releases/tag/eslint-plugin-fluid_v0.2.0)
 
 New rules added:

common/build/eslint-plugin-fluid/index.js

@@ -12,6 +12,12 @@
  */
 module.exports = {
 	rules: {
+		/**
+		 * Disallow `-` following JSDoc/TSDoc tags.
+		 * Full name: "@fluid-internal/fluid/no-hyphen-after-jsdoc-tag"
+		 */
+		"no-hyphen-after-jsdoc-tag": require("./src/rules/no-hyphen-after-jsdoc-tag"),
+
 		/**
 		 * Disallow file path links in JSDoc/TSDoc comments.
 		 * Full name: "@fluid-internal/fluid/no-file-path-links-in-jsdoc"

common/build/eslint-plugin-fluid/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fluid-internal/eslint-plugin-fluid",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Custom ESLint rules for the Fluid Framework",
 	"homepage": "https://fluidframework.com",
 	"repository": {

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

@@ -0,0 +1,61 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * JSDoc/TSDoc tags do not require a hyphen after them.
+ */
+module.exports = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Disallow hyphen character immediately following JSDoc tag",
+			category: "Best Practices",
+			recommended: false,
+		},
+		messages: {
+			hyphenAfterTag:
+				"JSDoc/TSDoc block tags should not be followed by a hyphen character ('-').",
+		},
+		fixable: "code",
+		schema: [],
+	},
+
+	create(context) {
+		return {
+			Program() {
+				const sourceCode = context.getSourceCode();
+				const comments = sourceCode
+					.getAllComments()
+					// Filter to only JSDoc/TSDoc style block comments
+					.filter((comment) => comment.type === "Block" && comment.value.startsWith("*"));
+
+				for (const comment of comments) {
+					// Find any JSDoc/TSDoc tags followed by a hyphen
+					const matches = comment.value.matchAll(/(@[a-zA-Z0-9]+)\s*?-(.*)/g);
+					for (const match of matches) {
+						const [fullMatch, tag, body] = match;
+
+						const startIndex = comment.range[0] + match.index;
+						const endIndex = startIndex + fullMatch.length;
+
+						context.report({
+							loc: {
+								start: sourceCode.getLocFromIndex(startIndex),
+								end: sourceCode.getLocFromIndex(endIndex),
+							},
+							messageId: "hyphenAfterTag",
+							fix(fixer) {
+								return fixer.replaceTextRange(
+									[startIndex, endIndex],
+									`${tag} ${body.trimStart()}`,
+								);
+							},
+						});
+					}
+				}
+			},
+		};
+	},
+};

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

@@ -0,0 +1,61 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+const assert = require("assert");
+const path = require("path");
+const { ESLint } = require("eslint");
+
+describe("Do not allow `-` following JSDoc/TSDoc tags", function () {
+	/**
+	 *
+	 * @param {string} file - Path to the file being linted. Relative to the `example/no-hyphen-after-jsdoc-tag` folder.
+	 * @returns
+	 */
+	async function lintFile(file) {
+		const eslint = new ESLint({
+			useEslintrc: false,
+			overrideConfig: {
+				rules: {
+					"no-hyphen-after-jsdoc-tag": "error",
+				},
+				parser: "@typescript-eslint/parser",
+				parserOptions: {
+					project: path.join(__dirname, "../example/tsconfig.json"),
+				},
+			},
+			rulePaths: [path.join(__dirname, "../../rules")],
+		});
+		const fileToLint = path.join(__dirname, "../example/no-hyphen-after-jsdoc-tag", file);
+		const results = await eslint.lintFiles([fileToLint]);
+		assert.equal(results.length, 1, "Expected a single result for linting a single file.");
+		return results[0];
+	}
+
+	const expectedErrorMessage =
+		"JSDoc/TSDoc block tags should not be followed by a hyphen character ('-').";
+
+	it("Should report errors JSDoc/TSDoc tags followed by a hyphen", async function () {
+		const result = await lintFile("test.ts");
+		assert.strictEqual(result.errorCount, 3);
+
+		// Error 1
+		assert.strictEqual(result.messages[0].message, expectedErrorMessage);
+		assert.strictEqual(result.messages[0].line, 8);
+		assert.strictEqual(result.messages[0].fix?.text, "@remarks Here are some remarks.");
+
+		// Error 2
+		assert.strictEqual(result.messages[1].message, expectedErrorMessage);
+		assert.strictEqual(result.messages[1].line, 9);
+		assert.strictEqual(
+			result.messages[1].fix?.text,
+			"@deprecated This function is deprecated, use something else.",
+		);
+
+		// Error 3
+		assert.strictEqual(result.messages[2].message, expectedErrorMessage);
+		assert.strictEqual(result.messages[2].line, 10);
+		assert.strictEqual(result.messages[2].fix?.text, "@returns The concatenated string.");
+	});
+});

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

@@ -0,0 +1,26 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * 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.
+ */
+function invalid<T>(param1: string, param2: T): string {
+	return `${param1} - ${param2}`;
+}
+
+/**
+ * I am a test function with pretty standard docs, and none of my tags have hyphens after them 🙂.
+ * @remarks Here are some remarks.
+ * @deprecated This function is deprecated, use something else.
+ * @returns The concatenated string.
+ * @param param1 - I am a param comment. Since my hyphen follows the param name, this is valid.
+ * @typeParam T - I am a type param comment. I am also valid.
+ */
+function valid<T>(param1: string, param2: T): string {
+	return `${param1} - ${param2}`;
+}

common/build/eslint-plugin-fluid/src/test/example/no-unchecked-record-access/indexedRecordOfStrings.ts

@@ -143,11 +143,11 @@ if (key in datastore) {
 }
 datastore[key][key] = {}; // ok: Accessing nested property key of datastore[key] is allowed because it is assigned in the else case
 
-if (indexedRecordOfStrings.a !== void(0)) {
+if (indexedRecordOfStrings.a !== void 0) {
 	indexedRecordOfStrings.a.length; // ok: Within a presence check, 'a' is guaranteed to be defined
 }
 
-if (indexedRecordOfStrings.a !== void(1)) {
+if (indexedRecordOfStrings.a !== void 1) {
 	indexedRecordOfStrings.a.length; // ok: Within a presence check, 'a' is guaranteed to be defined
 }