feat(eslint-plugin-fluid): Add rule to forbid the use of relative file path links in JSDoc/TSDoc comments (#25500)

Such links are not portable and will cause problems for external users.
Stable, externally accessible link targets should be used instead (for
example, other APIs or GitHub URLs).

Author: Josmithr

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

@@ -7,6 +7,9 @@ New rules added:
 - `@fluid-internal/fluid/no-markdown-links-in-jsdoc`: Forbids the use of Markdown link syntax in JSDoc/TSDoc comments.
     - Such links are not supported by TSDoc spec and are not supported by some of our tooling.
       `{@link}` syntax should be used instead.
+- `@fluid-internal/fluid/no-file-path-links-in-jsdoc`: Forbids the use of file paths in `{@link}` tags in JSDoc/TSDoc comments.
+    - Such links are not portable and will cause problems for external users.
+      Stable, externally accessible link targets should be used instead (for example, other APIs or GitHub URLs).
 
 ## [0.1.6](https://github.com/microsoft/FluidFramework/releases/tag/eslint-plugin-fluid_v0.1.6)
 

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

@@ -12,15 +12,23 @@
  */
 module.exports = {
 	rules: {
+		/**
+		 * Disallow file path links in JSDoc/TSDoc comments.
+		 * Full name: "@fluid-internal/fluid/no-file-path-links-in-jsdoc"
+		 */
+		"no-file-path-links-in-jsdoc": require("./src/rules/no-file-path-links-in-jsdoc"),
+
 		/**
 		 * Disallow Markdown link syntax in JSDoc/TSDoc comments.
 		 * Full name: "@fluid-internal/fluid/no-markdown-links-in-jsdoc"
 		 */
 		"no-markdown-links-in-jsdoc": require("./src/rules/no-markdown-links-in-jsdoc"),
+
 		/**
 		 * Full name: "@fluid-internal/fluid/no-member-release-tags"
 		 */
 		"no-member-release-tags": require("./src/rules/no-member-release-tags"),
+
 		"no-restricted-tags-imports": require("./src/rules/no-restricted-tags-imports"),
 		"no-unchecked-record-access": require("./src/rules/no-unchecked-record-access"),
 	},

common/build/eslint-plugin-fluid/src/rules/no-file-path-links-in-jsdoc.js

@@ -0,0 +1,58 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * File path links are not portable in the context of JSDoc/TSDoc comments.
+ * For this reason, we disallow them in favor of links to stable, user-accessible resources (like GitHub URLs).
+ * This rule enforces that file path links do not appear in `{@link}` tags in JSDoc/TSDoc comments.
+ *
+ * @remarks
+ * Our separate rule, `no-markdown-links-in-jsdoc`, disallows Markdown link syntax in JSDoc/TSDoc comments.
+ */
+module.exports = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Disallow relative path link syntax in comments",
+			category: "Best Practices",
+			recommended: false,
+		},
+		messages: {
+			filePathLink:
+				"File path links are not allowed in JSDoc/TSDoc comments. Link to a stable, user-accessible resource (like an API reference or a GitHub URL) instead.",
+		},
+		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) {
+					// JSDoc/TSDoc link syntax: {@link target|text} or {@link target}
+					// Find links where the `target` component is a file path (starts with `/`, `./`, or `../`)
+					const matches = comment.value.matchAll(/{@link\s+(\/|\.\/|\.\.\/).*}/g);
+					for (const match of matches) {
+						const startIndex = comment.range[0] + match.index;
+						const endIndex = startIndex + match[0].length;
+
+						context.report({
+							loc: {
+								start: sourceCode.getLocFromIndex(startIndex),
+								end: sourceCode.getLocFromIndex(endIndex),
+							},
+							messageId: "filePathLink",
+						});
+					}
+				}
+			},
+		};
+	},
+};

common/build/eslint-plugin-fluid/src/test/enforce-no-file-path-links-in-jsdoc/enforce-no-file-path-links-in-jsdoc.test.js

@@ -0,0 +1,54 @@
+/*!
+ * 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 file path links in JSDoc/TSDoc comments", function () {
+	async function lintFile(file) {
+		const eslint = new ESLint({
+			useEslintrc: false,
+			overrideConfig: {
+				rules: {
+					"no-file-path-links-in-jsdoc": "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-file-path-links-in-jsdoc", 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 =
+		"File path links are not allowed in JSDoc/TSDoc comments. Link to a stable, user-accessible resource (like an API reference or a GitHub URL) instead.";
+
+	it("Should report errors for file path links in block comments", async function () {
+		const result = await lintFile("test.ts");
+		assert.strictEqual(result.errorCount, 4);
+
+		// Error 1
+		assert.strictEqual(result.messages[0].message, expectedErrorMessage);
+		assert.strictEqual(result.messages[0].line, 10);
+
+		// Error 2
+		assert.strictEqual(result.messages[1].message, expectedErrorMessage);
+		assert.strictEqual(result.messages[1].line, 11);
+
+		// Error 3
+		assert.strictEqual(result.messages[2].message, expectedErrorMessage);
+		assert.strictEqual(result.messages[2].line, 16);
+
+		// Error 4
+		assert.strictEqual(result.messages[3].message, expectedErrorMessage);
+		assert.strictEqual(result.messages[3].line, 17);
+	});
+});

common/build/eslint-plugin-fluid/src/test/example/no-file-path-links-in-jsdoc/test.ts

@@ -0,0 +1,48 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+// #region Invalid cases
+
+// TSDoc comment with a relative path link should be flagged.
+/**
+ * TSDoc comment with link using a relative file path: {@link	./relative/path|text}.
+ * And another: {@link ../relative-path}.
+ */
+const tsdocCommentWithRelativePathLinks = "invalid";
+
+/**
+ * TSDoc comment with link using an absolute file path: {@link /absolute/path|text}.
+ * And another: {@link  /absolute-path}.
+ */
+const tsdocCommentWithAbsolutePathLinks = "invalid";
+
+// #endregion
+
+// #region Valid cases
+
+// TSDoc comment with no links should not be flagged.
+/**
+ * TSDoc comment with no links.
+ */
+const tsdocCommentWithNoLinks = "valid";
+
+// TSDoc comment with a URL link should be allowed.
+/**
+ * TSDoc comment with link with URL target: {@link https://bing.com|bing.com}.
+ * And another: {@link https://fluidframework.com}.
+ */
+const tsdocCommentWithValidDocsLink = "valid";
+
+// Block comment should not be flagged.
+/*
+ * Block comment with link using a file path: {@link ./relative/path|text}.
+ */
+const blockCommentWithRelativePathLink = "valid";
+
+// Line comment should not be flagged.
+// Line comment with link using a file path: {@link /absolute-path}.
+const lineCommentWithFilePathLink = "valid";
+
+// #endregion