fix(angular): install @typescript-eslint/utils when using relevant an…

…gular eslint v18 packages (#26418)

<!-- Please make sure you have read the submission guidelines before
posting an PR -->
<!--
https://github.com/nrwl/nx/blob/master/CONTRIBUTING.md#-submitting-a-pr
-->

<!-- Please make sure that your commit message follows our format -->
<!-- Example: `fix(nx): must begin with lowercase` -->

## Current Behavior
<!-- This is the behavior we have today -->

Angular ESLint v18 packages now have `@typescript-eslint/utils` as a
peer dependency, but new projects don't install it, and existing
projects are not getting it installed in a migration.

## Expected Behavior
<!-- This is the behavior we should expect with the changes in this PR
-->

The `@typescript-eslint/utils` should be installed when creating new
Angular projects and when migrating when the workspace has the relevant
Angular ESLint packages in v18.

## Related Issue(s)
<!-- Please link the issue being fixed so it gets closed when this is
merged. -->

Fixes #26408

packages/angular/migrations.json

@@ -395,6 +395,15 @@
       },
       "description": "Update the @angular/cli package version to ~18.0.0.",
       "factory": "./src/migrations/update-19-1-0/update-angular-cli"
+    },
+    "add-typescript-eslint-utils": {
+      "cli": "nx",
+      "version": "19.2.1-beta.0",
+      "requires": {
+        "@angular-eslint/eslint-plugin": ">=18.0.0"
+      },
+      "description": "Installs the '@typescript-eslint/utils' package when having installed '@angular-eslint/eslint-plugin' or '@angular-eslint/eslint-plugin-template' with version >=18.0.0.",
+      "factory": "./src/migrations/update-19-2-1/add-typescript-eslint-utils"
     }
   },
   "packageJsonUpdates": {

packages/angular/src/generators/add-linting/lib/add-angular-eslint-dependencies.ts

@@ -10,13 +10,19 @@ export function addAngularEsLintDependencies(
   tree: Tree,
   projectName: string
 ): GeneratorCallback {
-  const angularEslintVersionToInstall = versions(tree).angularEslintVersion;
+  const compatVersions = versions(tree);
+  const angularEslintVersionToInstall = compatVersions.angularEslintVersion;
   const devDependencies = {
     '@angular-eslint/eslint-plugin': angularEslintVersionToInstall,
     '@angular-eslint/eslint-plugin-template': angularEslintVersionToInstall,
     '@angular-eslint/template-parser': angularEslintVersionToInstall,
   };
 
+  if ('typescriptEslintVersion' in compatVersions) {
+    devDependencies['@typescript-eslint/utils'] =
+      compatVersions.typescriptEslintVersion;
+  }
+
   if (isBuildableLibraryProject(tree, projectName)) {
     const jsoncEslintParserVersionToInstall =
       versions(tree).jsoncEslintParserVersion;

packages/angular/src/migrations/update-19-2-1/add-typescript-eslint-utils.spec.ts

@@ -0,0 +1,76 @@
+import { readJson, updateJson, type Tree } from '@nx/devkit';
+import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
+import migration, {
+  typescriptEslintUtilsVersion,
+} from './add-typescript-eslint-utils';
+
+describe('add-typescript-eslint-utils migration', () => {
+  let tree: Tree;
+
+  beforeEach(() => {
+    tree = createTreeWithEmptyWorkspace();
+  });
+
+  it.each`
+    pkgName                                     | version
+    ${'@angular-eslint/eslint-plugin'}          | ${'18.0.0'}
+    ${'@angular-eslint/eslint-plugin'}          | ${'~18.0.0'}
+    ${'@angular-eslint/eslint-plugin'}          | ${'^18.0.0'}
+    ${'@angular-eslint/eslint-plugin'}          | ${'^19.0.0'}
+    ${'@angular-eslint/eslint-plugin-template'} | ${'18.0.0'}
+    ${'@angular-eslint/eslint-plugin-template'} | ${'~18.0.0'}
+    ${'@angular-eslint/eslint-plugin-template'} | ${'^18.0.0'}
+    ${'@angular-eslint/eslint-plugin-template'} | ${'^19.0.0'}
+  `(
+    'should add "@typescript-eslint/utils" as devDependencies when "$pkgName" is installed with version "$version"',
+    async ({ pkgName, version }) => {
+      updateJson(tree, 'package.json', (json) => {
+        json.devDependencies = {
+          ...json.devDependencies,
+          [`${[pkgName]}`]: `${version}`,
+        };
+        return json;
+      });
+
+      await migration(tree);
+
+      const { devDependencies } = readJson(tree, 'package.json');
+      expect(devDependencies['@typescript-eslint/utils']).toBe(
+        typescriptEslintUtilsVersion
+      );
+    }
+  );
+
+  it.each`
+    pkgName                                     | version
+    ${'@angular-eslint/eslint-plugin'}          | ${'17.0.0'}
+    ${'@angular-eslint/eslint-plugin'}          | ${'~17.0.0'}
+    ${'@angular-eslint/eslint-plugin'}          | ${'^17.0.0'}
+    ${'@angular-eslint/eslint-plugin-template'} | ${'17.0.0'}
+    ${'@angular-eslint/eslint-plugin-template'} | ${'~17.0.0'}
+    ${'@angular-eslint/eslint-plugin-template'} | ${'^17.0.0'}
+  `(
+    'should not add "@typescript-eslint/utils" when "$pkgName" is installed with version "$version"',
+    async ({ pkgName, version }) => {
+      updateJson(tree, 'package.json', (json) => {
+        json.devDependencies = {
+          ...json.devDependencies,
+          [`${[pkgName]}`]: `${version}`,
+        };
+        return json;
+      });
+
+      await migration(tree);
+
+      const { devDependencies } = readJson(tree, 'package.json');
+      expect(devDependencies['@typescript-eslint/utils']).toBeUndefined();
+    }
+  );
+
+  it('should not add "@typescript-eslint/utils" when "@angular-eslint/eslint-plugin" and "@angular-eslint/eslint-plugin-template" are not installed', async () => {
+    await migration(tree);
+
+    const { devDependencies } = readJson(tree, 'package.json');
+    expect(devDependencies['@typescript-eslint/utils']).toBeUndefined();
+  });
+});

packages/angular/src/migrations/update-19-2-1/add-typescript-eslint-utils.ts

@@ -0,0 +1,35 @@
+import {
+  addDependenciesToPackageJson,
+  formatFiles,
+  type Tree,
+} from '@nx/devkit';
+import {
+  getInstalledPackageVersion,
+  getInstalledPackageVersionInfo,
+} from '../../generators/utils/version-utils';
+
+export const typescriptEslintUtilsVersion = '^8.0.0-alpha.28';
+
+export default async function (tree: Tree) {
+  if (getInstalledPackageVersion(tree, '@typescript-eslint/utils')) {
+    return;
+  }
+
+  const eslintPluginVersionInfo =
+    getInstalledPackageVersionInfo(tree, '@angular-eslint/eslint-plugin') ??
+    getInstalledPackageVersionInfo(
+      tree,
+      '@angular-eslint/eslint-plugin-template'
+    );
+  if (!eslintPluginVersionInfo || eslintPluginVersionInfo.major < 18) {
+    return;
+  }
+
+  addDependenciesToPackageJson(
+    tree,
+    {},
+    { '@typescript-eslint/utils': typescriptEslintUtilsVersion }
+  );
+
+  await formatFiles(tree);
+}

packages/angular/src/utils/backward-compatible-versions.ts

@@ -16,9 +16,15 @@ export type PackageVersionNames =
   | CompatPackageVersionNames;
 
 export type VersionMap = {
-  angularV16: Record<CompatPackageVersionNames, string>;
+  angularV16: Record<
+    Exclude<CompatPackageVersionNames, 'typescriptEslintVersion'>,
+    string
+  >;
   angularV17: Record<
-    Exclude<CompatPackageVersionNames, 'ngUniversalVersion'>,
+    Exclude<
+      CompatPackageVersionNames,
+      'ngUniversalVersion' | 'typescriptEslintVersion'
+    >,
     string
   >;
 };

packages/angular/src/utils/versions.ts

@@ -17,6 +17,7 @@ export const browserSyncVersion = '^3.0.0';
 export const moduleFederationNodeVersion = '~1.0.5';
 
 export const angularEslintVersion = '^18.0.1';
+export const typescriptEslintVersion = '^8.0.0-alpha.28';
 export const tailwindVersion = '^3.0.2';
 export const postcssVersion = '^8.4.5';
 export const postcssUrlVersion = '~10.1.3';