feat(migrations): add schematic to migrate to signal queries (angular#58032)

This commit adds an automated `ng generate` schematic/migration for
converting decorator queries to signal queries, as good as possible.

PR Close angular#58032

Author: devversion

packages/core/schematics/BUILD.bazel

@@ -17,6 +17,7 @@ pkg_npm(
         "//packages/core/schematics/ng-generate/inject-migration:static_files",
         "//packages/core/schematics/ng-generate/route-lazy-loading:static_files",
         "//packages/core/schematics/ng-generate/signal-input-migration:static_files",
+        "//packages/core/schematics/ng-generate/signal-queries-migration:static_files",
         "//packages/core/schematics/ng-generate/standalone-migration:static_files",
     ],
     validate = False,
@@ -35,6 +36,7 @@ rollup_bundle(
         "//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/signal-input-migration:index.ts": "signal-input-migration",
+        "//packages/core/schematics/ng-generate/signal-queries-migration:index.ts": "signal-queries-migration",
         "//packages/core/schematics/migrations/explicit-standalone-flag:index.ts": "explicit-standalone-flag",
         "//packages/core/schematics/migrations/pending-tasks:index.ts": "pending-tasks",
     },
@@ -52,6 +54,7 @@ rollup_bundle(
         "//packages/core/schematics/ng-generate/inject-migration",
         "//packages/core/schematics/ng-generate/route-lazy-loading",
         "//packages/core/schematics/ng-generate/signal-input-migration",
+        "//packages/core/schematics/ng-generate/signal-queries-migration",
         "//packages/core/schematics/ng-generate/standalone-migration",
         "@npm//@rollup/plugin-commonjs",
         "@npm//@rollup/plugin-node-resolve",

packages/core/schematics/collection.json

@@ -29,6 +29,12 @@
       "factory": "./bundles/signal-input-migration#migrate",
       "schema": "./ng-generate/signal-input-migration/schema.json",
       "aliases": ["signal-inputs", "signal-input"]
+    },
+    "signal-queries-migration": {
+      "description": "Updates query declarations to signal queries, while also migrating all relevant references.",
+      "factory": "./bundles/signal-queries-migration#migrate",
+      "schema": "./ng-generate/signal-queries-migration/schema.json",
+      "aliases": ["signal-queries", "signal-query", "signal-query-migration"]
     }
   }
 }

packages/core/schematics/migrations/signal-queries-migration/BUILD.bazel

@@ -6,6 +6,7 @@ ts_library(
         ["**/*.ts"],
         exclude = ["*.spec.ts"],
     ),
+    visibility = ["//packages/core/schematics/ng-generate/signal-queries-migration:__pkg__"],
     deps = [
         "//packages/compiler",
         "//packages/compiler-cli",

packages/core/schematics/migrations/signal-queries-migration/migration.ts

@@ -15,6 +15,7 @@ import {
   confirmAsSerializable,
   MigrationStats,
   ProgramInfo,
+  projectFile,
   Replacement,
   Serializable,
   TsurgeComplexMigration,
@@ -47,9 +48,7 @@ import {removeQueryListToArrayCall} from './fn_to_array_removal';
 import {replaceQueryListGetCall} from './fn_get_replacement';
 import {checkForIncompatibleQueryListAccesses} from './incompatible_query_list_fns';
 import {replaceQueryListFirstAndLastReferences} from './fn_first_last_replacement';
-
-// TODO: Consider re-using inheritance logic from input migration
-// TODO: Consider re-using problematic pattern recognition logic from input migration
+import {MigrationConfig} from './migration_config';
 
 export interface CompilationUnitData {
   knownQueryFields: Record<ClassFieldUniqueKey, {fieldName: string; isMulti: boolean}>;
@@ -74,13 +73,17 @@ export class SignalQueriesMigration extends TsurgeComplexMigration<
   CompilationUnitData,
   GlobalUnitData
 > {
+  constructor(private readonly config: MigrationConfig = {}) {
+    super();
+  }
+
   override async analyze(info: ProgramInfo): Promise<Serializable<CompilationUnitData>> {
     assert(info.ngCompiler !== null, 'Expected queries migration to have an Angular program.');
     // TODO: This stage for this migration doesn't necessarily need a full
     // compilation unit program.
 
     // Pre-Analyze the program and get access to the template type checker.
-    const {templateTypeChecker} = await info.ngCompiler['ensureAnalyzed']();
+    const {templateTypeChecker} = info.ngCompiler['ensureAnalyzed']();
 
     const {sourceFiles, program} = info;
     const checker = program.getTypeChecker();
@@ -118,6 +121,7 @@ export class SignalQueriesMigration extends TsurgeComplexMigration<
         // eagerly detect such and later filter those problematic references that
         // turned out to refer to queries.
         // TODO: Consider skipping this extra work when running in non-batch mode.
+        // TODO: Also consider skipping if we know this query cannot be part.
         {
           shouldTrackClassReference: (_class) => false,
           attemptRetrieveDescriptorFromSymbol: (s) => getClassFieldDescriptorForSymbol(s, info),
@@ -200,9 +204,14 @@ export class SignalQueriesMigration extends TsurgeComplexMigration<
     const referenceResult: ReferenceResult<ClassFieldDescriptor> = {references: []};
     const sourceQueries: ExtractedQuery[] = [];
 
-    const isMigratedQuery = (id: ClassFieldUniqueKey) =>
-      globalMetadata.knownQueryFields[id] !== undefined &&
-      globalMetadata.problematicQueries[id] === undefined;
+    const isMigratedQuery = (descriptor: ClassFieldDescriptor) =>
+      globalMetadata.knownQueryFields[descriptor.key] !== undefined &&
+      globalMetadata.problematicQueries[descriptor.key] === undefined &&
+      (this.config.shouldMigrateQuery === undefined ||
+        this.config.shouldMigrateQuery(
+          descriptor,
+          projectFile(descriptor.node.getSourceFile(), info),
+        ));
 
     // Detect all queries in this unit.
     const queryWholeProgramVisitor = (node: ts.Node) => {
@@ -278,8 +287,9 @@ export class SignalQueriesMigration extends TsurgeComplexMigration<
     for (const extractedQuery of sourceQueries) {
       const node = extractedQuery.node;
       const sf = node.getSourceFile();
+      const descriptor = {key: extractedQuery.id, node: extractedQuery.node};
 
-      if (!isMigratedQuery(extractedQuery.id)) {
+      if (!isMigratedQuery(descriptor)) {
         updateFileState(filesWithIncompleteMigration, sf, extractedQuery.kind);
         continue;
       }
@@ -300,9 +310,9 @@ export class SignalQueriesMigration extends TsurgeComplexMigration<
     const referenceMigrationHost: ReferenceMigrationHost<ClassFieldDescriptor> = {
       printer,
       replacements,
-      shouldMigrateReferencesToField: (field) => isMigratedQuery(field.key),
+      shouldMigrateReferencesToField: (field) => isMigratedQuery(field),
       shouldMigrateReferencesToClass: (clazz) =>
-        !!knownQueries.getQueryFieldsOfClass(clazz)?.some((q) => isMigratedQuery(q.key)),
+        !!knownQueries.getQueryFieldsOfClass(clazz)?.some((q) => isMigratedQuery(q)),
     };
     migrateTypeScriptReferences(referenceMigrationHost, referenceResult.references, checker, info);
     migrateTemplateReferences(referenceMigrationHost, referenceResult.references);

packages/core/schematics/migrations/signal-queries-migration/migration_config.ts

@@ -0,0 +1,26 @@
+/**
+ * @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 {ProjectFile} from '../../utils/tsurge';
+import {ClassFieldDescriptor} from '../signal-migration/src';
+
+export interface MigrationConfig {
+  /**
+   * Whether the given query should be migrated. With batch execution, this
+   * callback fires for foreign queries from other compilation units too.
+   *
+   * Treating a query as non-migrated means that no references to it are
+   * migrated, nor the actual declaration (if it's part of the sources).
+   *
+   * If no function is specified here, the migration will migrate all
+   * inputs and references it discovers in compilation units. This is the
+   * running assumption for batch mode and LSC mode where the migration
+   * assumes all seen queries are migrated.
+   */
+  shouldMigrateQuery?: (query: ClassFieldDescriptor, file: ProjectFile) => boolean;
+}

packages/core/schematics/ng-generate/signal-queries-migration/BUILD.bazel

@@ -0,0 +1,29 @@
+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 = "signal-queries-migration",
+    srcs = glob(["**/*.ts"]),
+    tsconfig = "//packages/core/schematics:tsconfig.json",
+    deps = [
+        "//packages/compiler-cli/src/ngtsc/file_system",
+        "//packages/core/schematics/migrations/signal-queries-migration:migration",
+        "//packages/core/schematics/utils",
+        "//packages/core/schematics/utils/tsurge",
+        "//packages/core/schematics/utils/tsurge/helpers/angular_devkit",
+        "@npm//@angular-devkit/schematics",
+        "@npm//@types/node",
+    ],
+)

packages/core/schematics/ng-generate/signal-queries-migration/README.md

@@ -0,0 +1,81 @@
+# Signal queries migration
+
+The Angular team provides an automated migration for converting decorator
+queries to signal queries. E.g. `@ViewChild` will be converted to `viewChild()`.
+
+Aside from the query declarations, the migration will also take care of all
+references to updated queries.
+
+## How to run this migration?
+
+The migration can be run using the following command:
+
+```bash
+ng generate @angular/core:signal-queries-migration
+```
+
+## What does it change?
+
+1. `@ViewChild()`, `@ViewChildren`, `@ContentChild` and `@ContentChildren` class members
+   are updated to their signal equivalents.
+2. References in your application to migrated queries are updated to call the signal.
+   - This includes references in templates, host bindings or TypeScript code.
+
+**Before**
+
+```typescript
+import {Component, ContentChild} from '@angular/core';
+
+@Component({
+  template: `Has ref: {{someRef ? 'Yes' : 'No'}}`
+})
+export class MyComponent {
+  @ContentChild('someRef') ref: ElementRef|undefined = undefined;
+
+  someMethod() {
+    if (this.ref) {
+      this.ref.nativeElement;
+    }
+  }
+}
+```
+
+**After**
+
+```typescript
+import {Component, contentChild} from '@angular/core';
+
+@Component({
+  template: `Has ref: {{someRef() ? 'Yes' : 'No'}}`
+})
+export class MyComponent {
+  readonly ref = contentChild<ElementRef>('someRef');
+
+  someMethod() {
+    const refValue = this.ref();
+    if (refValue) {
+      refValue.nativeElement;
+    }
+  }
+}
+```
+
+## Configuration options
+
+The migration supports a few options to fine-tune the migration for your specific needs.
+
+### `--path`
+
+By default, the migration will update your whole Angular CLI workspace.
+You can limit the migration to a specific sub-directory using this option.
+
+### `--analysis-dir`
+
+Optional flag that can be used in large code projects.
+
+In large projects you may use this option to reduce the amount of files being analyzed.
+By default, the migration analyzes the whole workspace, regardless of the `--path` option, in
+order to update all references affected by a query declaration being migrated.
+
+With this option, you can limit analysis to a sub-folder. Note that this means that any
+references outside this directory are silently skipped, potentially breaking your build.

packages/core/schematics/ng-generate/signal-queries-migration/index.ts

@@ -0,0 +1,108 @@
+/**
+ * @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 {
+  CompilationUnitData,
+  SignalQueriesMigration,
+} from '../../migrations/signal-queries-migration/migration';
+
+interface Options {
+  path: string;
+  analysisDir: string;
+}
+
+export function migrate(options: Options): 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 run signal input migration.',
+      );
+    }
+
+    const fs = new DevkitMigrationFilesystem(tree);
+    setFileSystem(fs);
+
+    const migration = new SignalQueriesMigration({
+      shouldMigrateQuery: (_query, file) => {
+        return (
+          file.rootRelativePath.startsWith(fs.normalize(options.path)) &&
+          !/(^|\/)node_modules\//.test(file.rootRelativePath)
+        );
+      },
+    });
+    const analysisPath = fs.resolve(options.analysisDir);
+    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);
+
+      // Support restricting the analysis to subfolders for larger projects.
+      if (analysisPath !== '/') {
+        info.sourceFiles = info.sourceFiles.filter((sf) => sf.fileName.startsWith(analysisPath));
+        info.fullProgramSourceFiles = info.fullProgramSourceFiles.filter((sf) =>
+          sf.fileName.startsWith(analysisPath),
+        );
+      }
+
+      return {info, tsconfigPath};
+    });
+
+    // Analyze phase. Treat all projects as compilation units as
+    // this allows us to support references between those.
+    for (const {info, tsconfigPath} of programInfos) {
+      context.logger.info(`Scanning for queries: ${tsconfigPath}..`);
+
+      unitResults.push(await migration.analyze(info));
+    }
+
+    context.logger.info(``);
+    context.logger.info(`Processing analysis data between targets..`);
+    context.logger.info(``);
+
+    const merged = await migration.merge(unitResults);
+    const replacementsPerFile: Map<ProjectRootRelativePath, TextUpdate[]> = new Map();
+
+    for (const {info, tsconfigPath} of programInfos) {
+      context.logger.info(`Migrating: ${tsconfigPath}..`);
+
+      const replacements = await migration.migrate(merged, info);
+      const changesPerFile = groupReplacementsByFile(replacements);
+
+      for (const [file, changes] of changesPerFile) {
+        if (!replacementsPerFile.has(file)) {
+          replacementsPerFile.set(file, changes);
+        }
+      }
+    }
+
+    context.logger.info(`Applying 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);
+    }
+
+    context.logger.info('');
+    context.logger.info(`Successfully migrated to signal queries 🎉`);
+  };
+}

packages/core/schematics/ng-generate/signal-queries-migration/schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "AngularSignalQueriesMigration",
+  "title": "Angular Signal Queries migration",
+  "type": "object",
+  "properties": {
+    "path": {
+      "type": "string",
+      "description": "Path to the directory where all queries should be migrated.",
+      "x-prompt": "Which directory do you want to migrate?",
+      "default": "./"
+    },
+    "analysisDir": {
+      "type": "string",
+      "description": "Path to the directory that should be analyzed. References to migrated queries are migrated based on this folder. Useful for larger projects if the analysis takes too long and the analysis scope can be narrowed.",
+      "default": "./"
+    }
+  }
+}