refactor(migrations): support inserting TODOs for skipped input fields (angular#57898)

This is a helpful option to retrieve some insights on why certain inputs were not migrated. PR Close angular#57898

Author: devversion

packages/core/schematics/migrations/signal-migration/src/batch/merge_unit_data.ts

@@ -90,7 +90,5 @@ export function mergeCompilationUnitData(
  }
  }
 
- console.error(result);
-
  return result;
 }

packages/core/schematics/migrations/signal-migration/src/batch/test_bin.ts

@@ -22,7 +22,7 @@ main().catch((e) => {
 
 async function main() {
  const [mode, ...args] = process.argv.slice(2);
- const migration = new SignalInputMigration();
+ const migration = new SignalInputMigration({insertTodosForSkippedFields: true});
 
  if (mode === 'extract') {
  const analyzeResult = await executeAnalyzePhase(migration, path.resolve(args[0]));

packages/core/schematics/migrations/signal-migration/src/cli.ts

@@ -12,17 +12,26 @@ import assert from 'assert';
 import {SignalInputMigration} from './migration';
 import {writeMigrationReplacements} from './write_replacements';
 
-main(path.resolve(process.argv[2]), process.argv.includes('--best-effort-mode')).catch((e) => {
+main(
+ path.resolve(process.argv[2]),
+ process.argv.includes('--best-effort-mode'),
+ process.argv.includes('--insert-todos'),
+).catch((e) => {
  console.error(e);
  process.exitCode = 1;
 });
 
 /**
  * Runs the signal input migration for the given TypeScript project.
  */
-export async function main(absoluteTsconfigPath: string, bestEffortMode: boolean) {
+export async function main(
+ absoluteTsconfigPath: string,
+ bestEffortMode: boolean,
+ insertTodosForSkippedFields: boolean,
+) {
  const migration = new SignalInputMigration({
  bestEffortMode,
+ insertTodosForSkippedFields,
  upgradeAnalysisPhaseToAvoidBatch: true,
  });
  const baseInfo = migration.createProgram(absoluteTsconfigPath);

packages/core/schematics/migrations/signal-migration/src/input_detection/directive_info.ts

@@ -53,6 +53,13 @@ export class DirectiveInfo {
  * then the member is as well.
  */
  isInputMemberIncompatible(input: InputDescriptor): boolean {
- return this.incompatible !== null || this.memberIncompatibility.has(input.key);
+ return this.getInputMemberIncompatibility(input) !== null;
+ }
+
+ /** Get incompatibility of the given member, if it's incompatible for migration. */
+ getInputMemberIncompatibility(
+ input: InputDescriptor,
+ ): ClassIncompatibilityReason | InputMemberIncompatibility | null {
+ return this.incompatible ?? this.memberIncompatibility.get(input.key) ?? null;
  }
 }

packages/core/schematics/migrations/signal-migration/src/input_detection/incompatibility_human.ts

@@ -101,7 +101,7 @@ export function getMessageForClassIncompatibility(reason: ClassIncompatibilityRe
  case ClassIncompatibilityReason.ClassManuallyInstantiated:
  return {
  short:
- 'Class of this input is manually instantiated (`new Cmp()`). ' +
+ 'Class of this input is manually instantiated. ' +
  'This is discouraged and prevents migration',
  extra:
  'Signal inputs require a DI injection context. Manually instantiating ' +

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

@@ -15,6 +15,12 @@ export interface MigrationConfig {
  */
  bestEffortMode?: boolean;
 
+ /**
+ * Whether to insert TODOs for skipped fields, and reasons on why they
+ * were skipped.
+ */
+ insertTodosForSkippedFields?: boolean;
+
  /**
  * Whether the given input should be migrated. With batch execution, this
  * callback fires for foreign inputs from other compilation units too.

packages/core/schematics/migrations/signal-migration/src/passes/6_migrate_input_declarations.ts

@@ -6,19 +6,22 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
+import {ImportManager} from '@angular/compiler-cli/src/ngtsc/translator';
+import assert from 'assert';
 import ts from 'typescript';
-import {MigrationResult} from '../result';
+import {ProgramInfo, projectFile, Replacement, TextUpdate} from '../../../../utils/tsurge';
 import {convertToSignalInput} from '../convert-input/convert_to_signal';
-import assert from 'assert';
 import {KnownInputs} from '../input_detection/known_inputs';
-import {ImportManager} from '@angular/compiler-cli/src/ngtsc/translator';
-import {ProgramInfo, projectFile, Replacement, TextUpdate} from '../../../../utils/tsurge';
+import {MigrationHost} from '../migration_host';
+import {MigrationResult} from '../result';
+import {insertTodoForIncompatibility} from '../utils/incompatibility_todos';
 
 /**
  * Phase that migrates `@Input()` declarations to signal inputs and
  * manages imports within the given file.
  */
 export function pass6__migrateInputDeclarations(
+ host: MigrationHost,
  checker: ts.TypeChecker,
  result: MigrationResult,
  knownInputs: KnownInputs,
@@ -30,13 +33,20 @@ export function pass6__migrateInputDeclarations(
 
  for (const [input, metadata] of result.sourceInputs) {
  const sf = input.node.getSourceFile();
+ const inputInfo = knownInputs.get(input)!;
 
  // Do not migrate incompatible inputs.
- if (knownInputs.get(input)!.isIncompatible() || metadata === null) {
+ if (inputInfo.isIncompatible()) {
+ // Add a TODO for the incompatible input, if desired.
+ if (host.config.insertTodosForSkippedFields) {
+ result.replacements.push(...insertTodoForIncompatibility(input.node, info, inputInfo));
+ }
+
  filesWithIncompatibleInputs.add(sf);
  continue;
  }
 
+ assert(metadata !== null, `Expected metadata to exist for input isn't marked incompatible.`);
  assert(!ts.isAccessor(input.node), 'Accessor inputs are incompatible.');
 
  filesWithMigratedInputs.add(sf);

packages/core/schematics/migrations/signal-migration/src/phase_migrate.ts

@@ -54,7 +54,7 @@ export function executeMigrationPhase(
 
  // Migrate passes.
  pass5__migrateTypeScriptReferences(referenceMigrationHost, result.references, typeChecker, info);
- pass6__migrateInputDeclarations(typeChecker, result, knownInputs, importManager, info);
+ pass6__migrateInputDeclarations(host, typeChecker, result, knownInputs, importManager, info);
  pass7__migrateTemplateReferences(referenceMigrationHost, result.references);
  pass8__migrateHostBindings(referenceMigrationHost, result.references, info);
  pass9__migrateTypeScriptTypeReferences(

packages/core/schematics/migrations/signal-migration/src/utils/incompatibility_todos.ts

@@ -0,0 +1,71 @@
+/**
+ * @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.io/license
+ */
+
+import {KnownInputInfo} from '../input_detection/known_inputs';
+import {ProgramInfo, Replacement} from '../../../../utils/tsurge';
+import {isInputMemberIncompatibility} from '../input_detection/incompatibility';
+import {
+ getMessageForClassIncompatibility,
+ getMessageForInputIncompatibility,
+} from '../input_detection/incompatibility_human';
+import {insertPrecedingLine} from '../../../../utils/tsurge/helpers/ast/insert_preceding_line';
+import {InputNode} from '../input_detection/input_node';
+
+/**
+ * Inserts a TODO for the incompatibility blocking the given node
+ * from being migrated.
+ */
+export function insertTodoForIncompatibility(
+ node: InputNode,
+ programInfo: ProgramInfo,
+ input: KnownInputInfo,
+): Replacement[] {
+ const incompatibility = input.container.getInputMemberIncompatibility(input.descriptor);
+ if (incompatibility === null) {
+ return [];
+ }
+
+ const message = isInputMemberIncompatibility(incompatibility)
+ ? getMessageForInputIncompatibility(incompatibility.reason).short
+ : getMessageForClassIncompatibility(incompatibility).short;
+ const lines = cutStringToWordLimit(message, 70);
+
+ return [
+ insertPrecedingLine(node, programInfo, `// TODO: Skipped for migration because:`),
+ ...lines.map((line) => insertPrecedingLine(node, programInfo, `// ${line}`)),
+ ];
+}
+
+/**
+ * Cuts the given string into lines basing around the specified
+ * line length limit. This function breaks the string on a per-word basis.
+ */
+function cutStringToWordLimit(str: string, limit: number): string[] {
+ const words = str.split(' ');
+ const chunks: string[] = [];
+ let chunkIdx = 0;
+
+ while (words.length) {
+ // New line if we exceed limit.
+ if (chunks[chunkIdx] !== undefined && chunks[chunkIdx].length > limit) {
+ chunkIdx++;
+ }
+ // Ensure line is initialized for the given index.
+ if (chunks[chunkIdx] === undefined) {
+ chunks[chunkIdx] = '';
+ }
+
+ const word = words.shift();
+ const needsSpace = chunks[chunkIdx].length > 0;
+
+ // Insert word. Add space before, if the line already contains text.
+ chunks[chunkIdx] += `${needsSpace ? ' ' : ''}${word}`;
+ }
+
+ return chunks;
+}

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

@@ -38,7 +38,7 @@ integration_test(
  "//packages/core/schematics/migrations/signal-migration/test/golden-test:test_files",
  ],
  commands = [
- "$(rootpath //packages/core/schematics/migrations/signal-migration/src:bin) ./golden-test/tsconfig.json",
+ "$(rootpath //packages/core/schematics/migrations/signal-migration/src:bin) ./golden-test/tsconfig.json --insert-todos",
  "$(rootpath :golden_test_runner) ./golden-test ./golden.txt",
  ],
  data = [
@@ -60,7 +60,7 @@ integration_test(
  "//packages/core/schematics/migrations/signal-migration/test/ts-versions:loader.mjs",
  ],
  commands = [
- "$(rootpath //packages/core/schematics/migrations/signal-migration/src:bin) --node_options=--import=./ts-versions/loader.js ./golden-test/tsconfig.json",
+ "$(rootpath //packages/core/schematics/migrations/signal-migration/src:bin) --node_options=--import=./ts-versions/loader.js ./golden-test/tsconfig.json --insert-todos ",
  "$(rootpath :golden_test_runner) ./golden-test ./golden.txt",
  ],
  data = [
@@ -83,7 +83,7 @@ integration_test(
  "//packages/core/schematics/migrations/signal-migration/test/golden-test:test_files",
  ],
  commands = [
- "$(rootpath //packages/core/schematics/migrations/signal-migration/src:bin) ./golden-test/tsconfig.json --best-effort-mode",
+ "$(rootpath //packages/core/schematics/migrations/signal-migration/src:bin) ./golden-test/tsconfig.json --best-effort-mode --insert-todos",
  "$(rootpath :golden_test_runner) ./golden-test ./golden_best_effort.txt",
  ],
  data = [