feat(build-tools): migrate to ESLint 9 flat config with shared eslint-config-fluid

build-tools/DEV.md

@@ -130,3 +130,23 @@ The following dependencies are pinned to older major versions because newer vers
     - Issue: Version 17+ changed internal module structure and removed exported types
     - Error: `Cannot find module 'npm-check-updates/build/src/types/IndexType.js'` and type errors
     - Used in: `build-cli`
+
+### Workaround: ESLint Config Linked Dependency
+
+The `@fluidframework/eslint-config-fluid` package is referenced using `link:../common/build/eslint-config-fluid` because the package exists in the root workspace but build-tools is a separate pnpm workspace. When using `link:` protocol, transitive dependencies are **not** automatically installed.
+
+As a workaround, the following dependencies from `eslint-config-fluid` are duplicated in the build-tools root `package.json`:
+
+- `@eslint-community/eslint-plugin-eslint-comments`
+- `@eslint/eslintrc`
+- `@fluid-internal/eslint-plugin-fluid`
+- `@typescript-eslint/eslint-plugin`
+- `@typescript-eslint/parser`
+- `eslint-config-biome`
+- `eslint-plugin-depend`
+- `eslint-plugin-promise`
+- `eslint-plugin-react`
+- `eslint-plugin-react-hooks`
+- `eslint-plugin-unused-imports`
+
+**These dependencies can be removed** once `eslint-config-fluid` is published to npm and consumed via a normal version specifier instead of `link:`. At that point, pnpm will properly resolve and install all transitive dependencies automatically.

build-tools/eslint.config.base.mts

@@ -0,0 +1,126 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Shared ESLint configuration for build-tools packages.
+ *
+ * This module re-exports the minimalDeprecated config from @fluidframework/eslint-config-fluid
+ * and provides additional utilities for build-tools specific needs.
+ */
+
+import { minimalDeprecated } from "@fluidframework/eslint-config-fluid/flat.mts";
+import chaiFriendly from "eslint-plugin-chai-friendly";
+
+/**
+ * Build-tools specific rule overrides.
+ * These packages are internal tooling, not public Fluid Framework packages,
+ * so some rules from the shared config don't apply or are too strict.
+ */
+const buildToolsOverrides = {
+	rules: {
+		// Build-tools packages are internal tooling, not public packages.
+		// The no-internal-modules rule is designed for the Fluid Framework package structure.
+		"import-x/no-internal-modules": "off",
+
+		// Build-tools uses @deprecated internally for deprecation warnings.
+		// Keep as warning to track usage, but don't fail the build.
+		"import-x/no-deprecated": "warn",
+
+		// Build-tools are Node.js CLI tools that legitimately use Node built-in modules.
+		"import-x/no-nodejs-modules": "off",
+
+		// Import ordering is handled by Biome.
+		"import-x/order": "off",
+
+		// oclif commands require default exports.
+		"import-x/no-default-export": "off",
+
+		// Build-tools uses globby, execa, and other packages that have newer alternatives.
+		// TODO: Consider migrating to alternatives over time.
+		"depend/ban-dependencies": "off",
+
+		// This rule is too strict for build-tools internal code.
+		// TODO: Consider enabling and fixing violations.
+		"@typescript-eslint/strict-boolean-expressions": "off",
+
+		// This rule requires explicit handling of undefined for index signatures.
+		// TODO: Consider enabling and fixing violations.
+		"@fluid-internal/fluid/no-unchecked-record-access": "off",
+
+		// Build-tools has some files that don't follow strict naming conventions.
+		"unicorn/filename-case": "off",
+
+		// Prefer-regexp-exec is a style preference, not a correctness issue.
+		"@typescript-eslint/prefer-regexp-exec": "off",
+
+		// These rules are useful but require code changes to fix.
+		// TODO: Enable and fix violations.
+		"@typescript-eslint/prefer-readonly": "off",
+		"@typescript-eslint/promise-function-async": "off",
+		"@typescript-eslint/no-shadow": "off",
+
+		// JSDoc hyphen rules are stylistic.
+		"jsdoc/require-hyphen-before-param-description": "off",
+		"jsdoc/require-param-description": "off",
+
+		// Prefer template literals is stylistic.
+		"prefer-template": "off",
+
+		// Allow non-null assertions in build-tools (internal code).
+		"@typescript-eslint/no-non-null-assertion": "off",
+		"@typescript-eslint/no-unnecessary-type-assertion": "off",
+
+		// These rules require code changes. Disable for now.
+		"@typescript-eslint/prefer-nullish-coalescing": "off",
+		"@typescript-eslint/prefer-optional-chain": "off",
+		"@typescript-eslint/no-unsafe-return": "off",
+		"@typescript-eslint/no-floating-promises": "off",
+		"@typescript-eslint/unbound-method": "off",
+		"@typescript-eslint/consistent-type-definitions": "off",
+		"@typescript-eslint/prefer-promise-reject-errors": "off",
+		"@typescript-eslint/no-base-to-string": "off",
+		"@typescript-eslint/no-unsafe-unary-minus": "off",
+
+		// TSDoc hyphen rule.
+		"tsdoc/syntax": "warn",
+
+		// Unicorn prefer-type-error is stylistic.
+		"unicorn/prefer-type-error": "off",
+
+		// Spaced-comment is stylistic, handled by formatter.
+		"spaced-comment": "off",
+
+		// JSDoc/TSDoc tag hyphen rule.
+		"@fluid-internal/fluid/no-hyphen-after-jsdoc-tag": "off",
+
+		// Import namespace errors may be false positives with some libraries.
+		"import-x/namespace": "off",
+
+		// Allow importing eslint in policy check code.
+		"import-x/no-extraneous-dependencies": "off",
+	},
+};
+
+/**
+ * The base ESLint flat config from eslint-config-fluid with build-tools overrides.
+ */
+export const baseConfig = [...minimalDeprecated, buildToolsOverrides];
+
+/**
+ * Chai-friendly configuration for test files.
+ * Use this in packages that use chai for assertions.
+ */
+export const chaiFriendlyConfig = {
+	plugins: {
+		"chai-friendly": chaiFriendly,
+	},
+	rules: {
+		"no-unused-expressions": "off",
+		"@typescript-eslint/no-unused-expressions": "off",
+		"chai-friendly/no-unused-expressions": "error",
+	},
+};
+
+export { chaiFriendly };

build-tools/package.json

@@ -75,10 +75,18 @@
 		"@commitlint/cli": "^20.1.0",
 		"@commitlint/config-conventional": "^20.0.0",
 		"@commitlint/cz-commitlint": "^20.1.0",
+		"@eslint-community/eslint-plugin-eslint-comments": "^4.5.0",
+		"@eslint/eslintrc": "^3.3.3",
+		"@eslint/js": "^9.39.2",
+		"@fluid-internal/eslint-plugin-fluid": "^0.4.1",
 		"@fluid-tools/build-cli": "~0.60.0",
 		"@fluidframework/build-common": "^2.0.3",
 		"@fluidframework/build-tools": "~0.60.0",
+		"@fluidframework/eslint-config-fluid": "link:../common/build/eslint-config-fluid",
 		"@microsoft/api-extractor": "^7.55.1",
+		"@rushstack/eslint-plugin": "^0.22.1",
+		"@typescript-eslint/eslint-plugin": "^8.18.2",
+		"@typescript-eslint/parser": "^8.18.2",
 		"c8": "^10.1.3",
 		"commitizen": "^4.3.1",
 		"concurrently": "^9.2.1",
@@ -87,12 +95,27 @@
 		"copyfiles": "^2.4.1",
 		"cz-conventional-changelog": "^3.3.0",
 		"cz-customizable": "^7.5.1",
-		"eslint": "~8.57.0",
+		"eslint": "~9.39.2",
+		"eslint-config-biome": "^2.1.3",
+		"eslint-config-prettier": "~10.1.8",
+		"eslint-import-resolver-typescript": "^4.4.4",
+		"eslint-plugin-chai-friendly": "~1.1.0",
+		"eslint-plugin-depend": "~1.4.0",
+		"eslint-plugin-import-x": "~4.16.1",
+		"eslint-plugin-jsdoc": "~61.5.0",
+		"eslint-plugin-promise": "~7.2.1",
+		"eslint-plugin-react": "~7.37.5",
+		"eslint-plugin-react-hooks": "~7.0.1",
+		"eslint-plugin-tsdoc": "~0.5.0",
+		"eslint-plugin-unicorn": "~56.0.1",
+		"eslint-plugin-unused-imports": "~4.3.0",
 		"inquirer": "^9.3.7",
+		"jiti": "^2.6.1",
 		"rimraf": "^6.1.2",
 		"run-script-os": "^1.1.6",
 		"syncpack": "^13.0.4",
-		"typescript": "~5.4.5"
+		"typescript": "~5.4.5",
+		"typescript-eslint": "^8.52.0"
 	},
 	"packageManager": "pnpm@10.18.3+sha512.bbd16e6d7286fd7e01f6b3c0b3c932cda2965c06a908328f74663f10a9aea51f1129eea615134bf992831b009eabe167ecb7008b597f40ff9bc75946aadfb08d",
 	"engines": {
@@ -137,16 +160,13 @@
 			"oclif includes some AWS-related features, but we don't use them, so we ignore @aws-sdk peer dependencies."
 		],
 		"peerDependencyRules": {
-			"allowedVersions": {
-				"eslint": "8.51.0",
-				"@typescript-eslint/parser": "6.21.0"
-			},
 			"ignoreMissing": [
 				"@types/node",
 				"@aws-sdk/*"
 			]
 		},
 		"overrideComments": [
+			"eslint: jssm-viz-cli brings in ESLint 8.x as a transitive dependency. Force ESLint 9.x to ensure consistent version across the workspace.",
 			"oclif includes some AWS-related features, but we don't use them, so we override those dependencies with empty packages. This helps reduce lockfile churn since the deps release very frequently.",
 			"@types/node: To avoid duplicating the oclif package and adding a bunch of dependencies, force @types/node to a single version. For some reason version 22.8.0 can't be overridden, so use that to ensure a single version",
 			"@types/minimatch: @types/glob@7.x uses minimatch.IOptions and minimatch.IMinimatch interfaces. Force @types/minimatch@5 which includes these legacy type definitions.",
@@ -155,6 +175,7 @@
 		"overrides": {
 			"@types/glob>@types/minimatch": "~5.1.2",
 			"@types/node": "^22.19.1",
+			"eslint": "^9.39.2",
 			"json5@<1.0.2": "^1.0.2",
 			"json5@>=2.0.0 <2.2.2": "^2.2.2",
 			"mdast-util-gfm-footnote": "^2.1.0",

build-tools/packages/build-cli/eslint.config.mts

@@ -0,0 +1,26 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { baseConfig } from "../../eslint.config.base.mts";
+
+export default [
+	...baseConfig,
+	// Ignore test data files and test fixtures that aren't in tsconfig
+	{
+		ignores: ["src/test/data/**", "src/test/**/fixtures/**"],
+	},
+	{
+		rules: {
+			// This rule is often triggered when using custom Flags, so disabling.
+			"object-shorthand": "off",
+
+			// oclif uses default exports for commands
+			"no-restricted-exports": "off",
+
+			// The default for this rule is 4, but 5 is better
+			"max-params": ["warn", 5],
+		},
+	},
+];

build-tools/packages/build-cli/package.json

@@ -143,7 +143,6 @@
 	"devDependencies": {
 		"@biomejs/biome": "~1.9.4",
 		"@fluidframework/build-common": "^2.0.3",
-		"@fluidframework/eslint-config-fluid": "^8.1.0",
 		"@oclif/test": "^4.1.15",
 		"@types/async": "^3.2.25",
 		"@types/chai": "^5.2.3",
@@ -166,10 +165,7 @@
 		"chai-arrays": "^2.2.0",
 		"concurrently": "^9.2.1",
 		"copyfiles": "^2.4.1",
-		"eslint": "~8.57.0",
-		"eslint-config-oclif": "^5.2.2",
-		"eslint-config-oclif-typescript": "^3.1.12",
-		"eslint-config-prettier": "~9.1.2",
+		"eslint": "~9.39.2",
 		"jssm-viz-cli": "^5.101.0",
 		"mocha": "^11.7.5",
 		"mocha-multi-reporters": "^1.5.1",