refactor(migrations): support statistic tracking in tsurge migrations (angular#58019)

We should support tracking statistics in Tsurge migrations. This allows
us to print them after migration, or run migrations periodically as
large scale changes to track to progress.

TODO is an internal implementation that eventually runs periodcally
in LSC modes.

PR Close angular#58019

Author: devversion

packages/core/schematics/utils/tsurge/base_migration.ts

@@ -11,14 +11,27 @@ import {isShim} from '@angular/compiler-cli/src/ngtsc/shims';
 import {createNgtscProgram} from './helpers/ngtsc_program';
 import {BaseProgramInfo, ProgramInfo} from './program_info';
 import {getRootDirs} from '@angular/compiler-cli/src/ngtsc/util/src/typescript';
+import {Serializable} from './helpers/serializable';
 
 /**
+ * Type describing statistics that could be tracked
+ * by migrations.
+ *
+ * Statistics may be tracked depending on the runner.
+ */
+export interface MigrationStats {
+  counters: Record<string, number>;
+}
+
+/**
+ * @private
+ *
  * Base class for the possible Tsurge migration variants.
  *
  * For example, this class exposes methods to conveniently create
  * TypeScript programs, while also allowing migration authors to override.
  */
-export abstract class TsurgeBaseMigration {
+export abstract class TsurgeBaseMigration<UnitAnalysisMetadata, CombinedGlobalMetadata> {
   // By default, ngtsc programs are being created.
   createProgram(tsconfigAbsPath: string, fs?: FileSystem): BaseProgramInfo {
     return createNgtscProgram(tsconfigAbsPath, fs);
@@ -56,4 +69,13 @@ export abstract class TsurgeBaseMigration {
       projectRoot: primaryRoot,
     };
   }
+
+  /** Analyzes the given TypeScript project and returns serializable compilation unit data. */
+  abstract analyze(info: ProgramInfo): Promise<Serializable<UnitAnalysisMetadata>>;
+
+  /** Merges all compilation unit data from previous analysis phases into a global result. */
+  abstract merge(units: UnitAnalysisMetadata[]): Promise<Serializable<CombinedGlobalMetadata>>;
+
+  /** Extract statistics based on the global metadata. */
+  abstract stats(globalMetadata: CombinedGlobalMetadata): Promise<MigrationStats>;
 }

packages/core/schematics/utils/tsurge/index.ts

@@ -6,6 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+export * from './base_migration';
 export * from './migration';
 export * from './program_info';
 export * from './replacement';

packages/core/schematics/utils/tsurge/migration.ts

@@ -54,14 +54,7 @@ export type TsurgeMigration<UnitAnalysisMetadata, CombinedGlobalMetadata> =
 export abstract class TsurgeFunnelMigration<
   UnitAnalysisMetadata,
   CombinedGlobalMetadata,
-  PreparationInfo = ProgramInfo,
-> extends TsurgeBaseMigration {
-  /** Analyzes the given TypeScript project and returns serializable compilation unit data. */
-  abstract analyze(info: PreparationInfo): Promise<Serializable<UnitAnalysisMetadata>>;
-
-  /** Merges all compilation unit data from previous analysis phases into a global result. */
-  abstract merge(units: UnitAnalysisMetadata[]): Promise<Serializable<CombinedGlobalMetadata>>;
-
+> extends TsurgeBaseMigration<UnitAnalysisMetadata, CombinedGlobalMetadata> {
   /**
    * Finalizes the migration result.
    *
@@ -86,13 +79,7 @@ export abstract class TsurgeFunnelMigration<
 export abstract class TsurgeComplexMigration<
   UnitAnalysisMetadata,
   CombinedGlobalMetadata,
-> extends TsurgeBaseMigration {
-  /** Analyzes the given TypeScript project and returns serializable compilation unit data. */
-  abstract analyze(info: ProgramInfo): Promise<Serializable<UnitAnalysisMetadata>>;
-
-  /** Merges all compilation unit data from previous analysis phases into a global result. */
-  abstract merge(units: UnitAnalysisMetadata[]): Promise<Serializable<CombinedGlobalMetadata>>;
-
+> extends TsurgeBaseMigration<UnitAnalysisMetadata, CombinedGlobalMetadata> {
   /**
    * Migration phase. Workers will be started for every compilation unit again,
    * instantiating a new program for every unit to compute the final migration

packages/core/schematics/utils/tsurge/test/output_migration.ts

@@ -14,6 +14,7 @@ import {ProgramInfo} from '../program_info';
 import {Replacement, TextUpdate} from '../replacement';
 import {findOutputDeclarationsAndReferences, OutputID} from './output_helpers';
 import {projectFile} from '../project_paths';
+import {MigrationStats} from '../base_migration';
 
 type AnalysisUnit = {[id: OutputID]: {seenProblematicUsage: boolean}};
 type GlobalMetadata = {[id: OutputID]: {canBeMigrated: boolean}};
@@ -107,4 +108,23 @@ export class OutputMigration extends TsurgeComplexMigration<AnalysisUnit, Global
 
     return replacements;
   }
+
+  override async stats(globalMetadata: GlobalMetadata): Promise<MigrationStats> {
+    let allOutputs = 0;
+    let migratedOutputs = 0;
+
+    for (const output of Object.values(globalMetadata)) {
+      allOutputs++;
+      if (output.canBeMigrated) {
+        migratedOutputs++;
+      }
+    }
+
+    return {
+      counters: {
+        allOutputs,
+        migratedOutputs,
+      },
+    };
+  }
 }