Merge branch 'main' into RemoveJsonValidatorExport

Author: CraigMacomber

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
 }
 

packages/dds/matrix/src/test/fuzz.ts

@@ -19,6 +19,8 @@ import { isFluidHandle, toFluidHandleInternal } from "@fluidframework/runtime-ut
 import type { MatrixItem } from "../ops.js";
 import { SharedMatrix, type SharedMatrixFactory } from "../runtime.js";
 
+import { hasSharedMatrixOracle } from "./matrixOracle.js";
+
 /**
  * Supported cell values used within the fuzz model.
  */
@@ -225,7 +227,17 @@ export const baseSharedMatrixModel: Omit<
 	factory: SharedMatrix.getFactory(),
 	generatorFactory: () => takeAsync(50, makeGenerator()),
 	reducer: (state, operation) => reducer(state, operation),
-	validateConsistency: async (a, b) => assertMatricesAreEquivalent(a.channel, b.channel),
+	validateConsistency: async (a, b) => {
+		if (hasSharedMatrixOracle(a.channel)) {
+			a.channel.matrixOracle.validate();
+		}
+
+		if (hasSharedMatrixOracle(b.channel)) {
+			b.channel.matrixOracle.validate();
+		}
+
+		return assertMatricesAreEquivalent(a.channel, b.channel);
+	},
 	minimizationTransforms: ["count", "start", "row", "col"].map((p) => (op) => {
 		if (p in op && typeof op[p] === "number" && op[p] > 0) {
 			op[p]--;

packages/dds/matrix/src/test/matrix.fuzz.spec.ts

@@ -3,19 +3,29 @@
  * Licensed under the MIT License.
  */
 
-import * as path from "node:path";
-
+import { TypedEventEmitter } from "@fluid-internal/client-utils";
 import {
 	createDDSFuzzSuite,
+	registerOracle,
+	type DDSFuzzHarnessEvents,
 	type DDSFuzzModel,
 	type DDSFuzzSuiteOptions,
 } from "@fluid-private/test-dds-utils";
 import { FlushMode } from "@fluidframework/runtime-definitions/internal";
 
 import type { SharedMatrixFactory } from "../runtime.js";
 
-import { _dirname } from "./dirname.cjs";
 import { baseSharedMatrixModel, type Operation } from "./fuzz.js";
+import { SharedMatrixOracle, type IChannelWithOracles } from "./matrixOracle.js";
+
+const oracleEmitter = new TypedEventEmitter<DDSFuzzHarnessEvents>();
+
+oracleEmitter.on("clientCreate", (client) => {
+	const channel = client.channel as IChannelWithOracles;
+	const sharedMatrixOracle = new SharedMatrixOracle(channel);
+	channel.matrixOracle = sharedMatrixOracle;
+	registerOracle(sharedMatrixOracle);
+});
 
 describe("Matrix fuzz tests", function () {
 	/**
@@ -39,7 +49,7 @@ describe("Matrix fuzz tests", function () {
 			clientAddProbability: 0.1,
 		},
 		reconnectProbability: 0,
-		saveFailures: { directory: path.join(_dirname, "../../src/test/results") },
+		emitter: oracleEmitter,
 	};
 
 	const nameModel = (workloadName: string): DDSFuzzModel<SharedMatrixFactory, Operation> => ({