feat(migrations): add schematic to clean up unused imports (#59353)

crisbeto · thePunderWoman · commit d298d254269f · 2025-01-06T16:21:26.000Z
In v19 we added a warning about unused standalone imports, however we didn't do anything about existing code which means that users have to clean it up manually. These changes add the `ng g @angular/core:cleanup-unused-imports` schematic which will remove the unused dependencies automatically. There isn't any new detection code since all the manipulations are based on the produced diagnostics, but there's a bit of code to remove the import declarations from the file as well. Fixes #58849. PR Close #59353
diff --git a/packages/core/schematics/BUILD.bazel b/packages/core/schematics/BUILD.bazel
@@ -1,5 +1,5 @@
-load("//tools:defaults.bzl", "pkg_npm")
 load("@npm//@bazel/rollup:index.bzl", "rollup_bundle")
+load("//tools:defaults.bzl", "pkg_npm")
 
 exports_files([
     "tsconfig.json",
@@ -13,6 +13,7 @@ pkg_npm(
         "collection.json",
         "migrations.json",
         "package.json",
+        "//packages/core/schematics/ng-generate/cleanup-unused-imports:static_files",
         "//packages/core/schematics/ng-generate/control-flow-migration:static_files",
         "//packages/core/schematics/ng-generate/inject-migration:static_files",
         "//packages/core/schematics/ng-generate/output-migration:static_files",
@@ -37,6 +38,7 @@ rollup_bundle(
         "//packages/core/schematics/ng-generate/inject-migration:index.ts": "inject-migration",
         "//packages/core/schematics/ng-generate/route-lazy-loading:index.ts": "route-lazy-loading",
         "//packages/core/schematics/ng-generate/standalone-migration:index.ts": "standalone-migration",
+        "//packages/core/schematics/ng-generate/cleanup-unused-imports:index.ts": "cleanup-unused-imports",
         "//packages/core/schematics/ng-generate/signals:index.ts": "signals",
         "//packages/core/schematics/ng-generate/signal-input-migration:index.ts": "signal-input-migration",
         "//packages/core/schematics/ng-generate/signal-queries-migration:index.ts": "signal-queries-migration",
@@ -56,6 +58,7 @@ rollup_bundle(
         "//packages/core/schematics/migrations/explicit-standalone-flag",
         "//packages/core/schematics/migrations/pending-tasks",
         "//packages/core/schematics/migrations/provide-initializer",
+        "//packages/core/schematics/ng-generate/cleanup-unused-imports",
         "//packages/core/schematics/ng-generate/control-flow-migration",
         "//packages/core/schematics/ng-generate/inject-migration",
         "//packages/core/schematics/ng-generate/output-migration",
diff --git a/packages/core/schematics/collection.json b/packages/core/schematics/collection.json
@@ -46,6 +46,11 @@
       "description": "Combines all signals-related migrations into a single migration",
       "factory": "./bundles/signals#migrate",
       "schema": "./ng-generate/signals/schema.json"
+    },
+    "cleanup-unused-imports": {
+      "description": "Removes unused imports from standalone components.",
+      "factory": "./bundles/cleanup-unused-imports#migrate",
+      "schema": "./ng-generate/cleanup-unused-imports/schema.json"
     }
   }
 }
diff --git a/packages/core/schematics/ng-generate/cleanup-unused-imports/BUILD.bazel b/packages/core/schematics/ng-generate/cleanup-unused-imports/BUILD.bazel
@@ -0,0 +1,32 @@
+load("//tools:defaults.bzl", "ts_library")
+
+package(
+    default_visibility = [
+        "//packages/core/schematics:__pkg__",
+        "//packages/core/schematics/migrations/google3:__pkg__",
+        "//packages/core/schematics/test:__pkg__",
+    ],
+)
+
+filegroup(
+    name = "static_files",
+    srcs = ["schema.json"],
+)
+
+ts_library(
+    name = "cleanup-unused-imports",
+    srcs = glob(["**/*.ts"]),
+    tsconfig = "//packages/core/schematics:tsconfig.json",
+    deps = [
+        "//packages/compiler-cli",
+        "//packages/compiler-cli/private",
+        "//packages/compiler-cli/src/ngtsc/core:api",
+        "//packages/compiler-cli/src/ngtsc/file_system",
+        "//packages/core/schematics/utils",
+        "//packages/core/schematics/utils/tsurge",
+        "//packages/core/schematics/utils/tsurge/helpers/angular_devkit",
+        "@npm//@angular-devkit/schematics",
+        "@npm//@types/node",
+        "@npm//typescript",
+    ],
+)
diff --git a/packages/core/schematics/ng-generate/cleanup-unused-imports/README.md b/packages/core/schematics/ng-generate/cleanup-unused-imports/README.md
@@ -0,0 +1,30 @@
+## Cleanup unused imports migration
+Automated migration that removes all unused standalone imports across the entire project. It can be
+run using:
+
+```bash
+ng generate @angular/core:cleanup-unused-imports
+```
+
+**Before:**
+```typescript
+import { Component } from '@angular/core';
+import { UnusedDirective } from './unused';
+
+@Component({
+  template: 'Hello',
+  imports: [UnusedDirective],
+})
+export class MyComp {}
+```
+
+**After:**
+```typescript
+import { Component } from '@angular/core';
+
+@Component({
+  template: 'Hello',
+  imports: [],
+})
+export class MyComp {}
+```
diff --git a/packages/core/schematics/ng-generate/cleanup-unused-imports/index.ts b/packages/core/schematics/ng-generate/cleanup-unused-imports/index.ts
@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {Rule, SchematicsException} from '@angular-devkit/schematics';
+
+import {getProjectTsConfigPaths} from '../../utils/project_tsconfig_paths';
+import {DevkitMigrationFilesystem} from '../../utils/tsurge/helpers/angular_devkit/devkit_filesystem';
+import {groupReplacementsByFile} from '../../utils/tsurge/helpers/group_replacements';
+import {setFileSystem} from '@angular/compiler-cli/src/ngtsc/file_system';
+import {ProjectRootRelativePath, TextUpdate} from '../../utils/tsurge';
+import {synchronouslyCombineUnitData} from '../../utils/tsurge/helpers/combine_units';
+import {CompilationUnitData, UnusedImportsMigration} from './unused_imports_migration';
+
+export function migrate(): Rule {
+  return async (tree, context) => {
+    const {buildPaths, testPaths} = await getProjectTsConfigPaths(tree);
+
+    if (!buildPaths.length && !testPaths.length) {
+      throw new SchematicsException(
+        'Could not find any tsconfig file. Cannot clean up unused imports.',
+      );
+    }
+
+    const fs = new DevkitMigrationFilesystem(tree);
+    setFileSystem(fs);
+
+    const migration = new UnusedImportsMigration();
+    const unitResults: CompilationUnitData[] = [];
+    const programInfos = [...buildPaths, ...testPaths].map((tsconfigPath) => {
+      context.logger.info(`Preparing analysis for ${tsconfigPath}`);
+
+      const baseInfo = migration.createProgram(tsconfigPath, fs);
+      const info = migration.prepareProgram(baseInfo);
+
+      return {info, tsconfigPath};
+    });
+
+    for (const {info, tsconfigPath} of programInfos) {
+      context.logger.info(`Scanning for unused imports using ${tsconfigPath}`);
+      unitResults.push(await migration.analyze(info));
+    }
+
+    const combined = await synchronouslyCombineUnitData(migration, unitResults);
+    if (combined === null) {
+      context.logger.error('Schematic failed unexpectedly with no analysis data');
+      return;
+    }
+
+    const globalMeta = await migration.globalMeta(combined);
+    const replacementsPerFile: Map<ProjectRootRelativePath, TextUpdate[]> = new Map();
+    const {replacements} = await migration.migrate(globalMeta);
+    const changesPerFile = groupReplacementsByFile(replacements);
+
+    for (const [file, changes] of changesPerFile) {
+      if (!replacementsPerFile.has(file)) {
+        replacementsPerFile.set(file, changes);
+      }
+    }
+
+    for (const [file, changes] of replacementsPerFile) {
+      const recorder = tree.beginUpdate(file);
+      for (const c of changes) {
+        recorder
+          .remove(c.data.position, c.data.end - c.data.position)
+          .insertLeft(c.data.position, c.data.toInsert);
+      }
+      tree.commitUpdate(recorder);
+    }
+
+    const {
+      counters: {removedImports, changedFiles},
+    } = await migration.stats(globalMeta);
+    let statsMessage: string;
+
+    if (removedImports === 0) {
+      statsMessage = 'Schematic could not find unused imports in the project';
+    } else {
+      statsMessage =
+        `Removed ${removedImports} import${removedImports !== 1 ? 's' : ''} ` +
+        `in ${changedFiles} file${changedFiles !== 1 ? 's' : ''}`;
+    }
+
+    context.logger.info('');
+    context.logger.info(statsMessage);
+  };
+}
diff --git a/packages/core/schematics/ng-generate/cleanup-unused-imports/schema.json b/packages/core/schematics/ng-generate/cleanup-unused-imports/schema.json
@@ -0,0 +1,7 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "AngularCleanupUnusedImportsMigration",
+  "title": "Angular Cleanup Unused Imports Schema",
+  "type": "object",
+  "properties": {}
+}
diff --git a/packages/core/schematics/ng-generate/cleanup-unused-imports/unused_imports_migration.ts b/packages/core/schematics/ng-generate/cleanup-unused-imports/unused_imports_migration.ts
diff --git a/packages/core/schematics/test/BUILD.bazel b/packages/core/schematics/test/BUILD.bazel
diff --git a/packages/core/schematics/test/cleanup_unused_imports_migration_spec.ts b/packages/core/schematics/test/cleanup_unused_imports_migration_spec.ts

Original file line number	Diff line number	Diff line change
`@@ -46,6 +46,11 @@`
`46`	`46`	`"description": "Combines all signals-related migrations into a single migration",`
`47`	`47`	`"factory": "./bundles/signals#migrate",`
`48`	`48`	`"schema": "./ng-generate/signals/schema.json"`
	`49`	`+ },`
	`50`	`+ "cleanup-unused-imports": {`
	`51`	`+ "description": "Removes unused imports from standalone components.",`
	`52`	`+ "factory": "./bundles/cleanup-unused-imports#migrate",`
	`53`	`+ "schema": "./ng-generate/cleanup-unused-imports/schema.json"`
`49`	`54`	`}`
`50`	`55`	`}`
`51`	`56`	`}`