refactor(@angular/cli): add a get Zoneless/OnPush MCP tool

This change adds a tool that identifies the next steps for migrating a
project file or directory to Zoneless or OnPush. The priorities for
migration are:

1. Find and report any unsupported uses of ZoneJS APIs. These are easily
   verifiable. If they exist, they need to be removed and the tool
   provides suggested replacements
2. Provide requirements for OnPush compatibility for any files with a
   Component. It is suggested to use an explicit `ChangeDetectionStrategy.Default`
   until it can be verified the migration is complete. The tool skips
   any components with explicit change detection strategy definitions.
   This is required since we have no way of statically verifying a
   component is compatible with OnPush, so we need some way to indicate
   the tool should move on from a component
3. When nothing is identified in the above two steps, move on to test
   files and suggest migrating those to use zoneless. This is the best
   method to verify that components are zoneless compatible.

(cherry picked from commit e8111a9)

Author: atscott

packages/angular/cli/BUILD.bazel

@@ -72,6 +72,7 @@ ts_project(
         "//:node_modules/@types/yarnpkg__lockfile",
         "//:node_modules/listr2",
         "//:node_modules/semver",
+        "//:node_modules/typescript",
     ],
 )
 
@@ -124,10 +125,12 @@ ts_project(
         ":angular-cli",
         ":node_modules/@angular-devkit/core",
         ":node_modules/@angular-devkit/schematics",
+        ":node_modules/@modelcontextprotocol/sdk",
         ":node_modules/yargs",
         "//:node_modules/@types/semver",
         "//:node_modules/@types/yargs",
         "//:node_modules/semver",
+        "//:node_modules/typescript",
     ],
 )
 

packages/angular/cli/src/commands/mcp/mcp-server.ts

@@ -15,6 +15,7 @@ import { BEST_PRACTICES_TOOL } from './tools/best-practices';
 import { DOC_SEARCH_TOOL } from './tools/doc-search';
 import { FIND_EXAMPLE_TOOL } from './tools/examples';
 import { MODERNIZE_TOOL } from './tools/modernize';
+import { ZONELESS_MIGRATION_TOOL } from './tools/onpush-zoneless-migration/zoneless-migration';
 import { LIST_PROJECTS_TOOL } from './tools/projects';
 import { AnyMcpToolDeclaration, registerTools } from './tools/tool-registry';
 
@@ -28,7 +29,11 @@ const STABLE_TOOLS = [BEST_PRACTICES_TOOL, DOC_SEARCH_TOOL, LIST_PROJECTS_TOOL]
  * The set of tools that are available but not enabled by default.
  * These tools are considered experimental and may have limitations.
  */
-export const EXPERIMENTAL_TOOLS = [FIND_EXAMPLE_TOOL, MODERNIZE_TOOL] as const;
+export const EXPERIMENTAL_TOOLS = [
+  FIND_EXAMPLE_TOOL,
+  MODERNIZE_TOOL,
+  ZONELESS_MIGRATION_TOOL,
+] as const;
 
 export async function createMcpServer(
   options: {

packages/angular/cli/src/commands/mcp/tools/onpush-zoneless-migration/analyze_for_unsupported_zone_uses.ts

@@ -0,0 +1,76 @@
+/**
+ * @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 type { ImportSpecifier, Node, SourceFile } from 'typescript';
+import { createUnsupportedZoneUsagesMessage } from './prompts';
+import { getImportSpecifier, loadTypescript } from './ts_utils';
+import { MigrationResponse } from './types';
+
+export async function analyzeForUnsupportedZoneUses(
+  sourceFile: SourceFile,
+): Promise<MigrationResponse | null> {
+  const ngZoneImport = await getImportSpecifier(sourceFile, '@angular/core', 'NgZone');
+  if (!ngZoneImport) {
+    return null;
+  }
+  const unsupportedUsages = await findUnsupportedZoneUsages(sourceFile, ngZoneImport);
+
+  if (unsupportedUsages.length === 0) {
+    return null;
+  }
+
+  const locations = unsupportedUsages.map((node: Node) => {
+    const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+
+    return `line ${line + 1}, character ${character + 1}: ${node.getText()}`;
+  });
+
+  return createUnsupportedZoneUsagesMessage(locations, sourceFile.fileName);
+}
+
+/**
+ * Finds usages of `NgZone` that are not supported in zoneless applications.
+ * @param sourceFile The source file to check.
+ * @param ngZoneImport The import specifier for `NgZone`.
+ * @returns A list of nodes that are unsupported `NgZone` usages.
+ */
+export async function findUnsupportedZoneUsages(
+  sourceFile: SourceFile,
+  ngZoneImport: ImportSpecifier,
+): Promise<Node[]> {
+  const unsupportedUsages: Node[] = [];
+  const ngZoneClassName = ngZoneImport.name.text;
+
+  const staticMethods = new Set([
+    'isInAngularZone',
+    'assertInAngularZone',
+    'assertNotInAngularZone',
+  ]);
+  const instanceMethods = new Set(['onMicrotaskEmpty', 'onStable']);
+
+  const ts = await loadTypescript();
+  ts.forEachChild(sourceFile, function visit(node) {
+    if (ts.isPropertyAccessExpression(node)) {
+      const propertyName = node.name.text;
+      const expressionText = node.expression.getText(sourceFile);
+
+      // Static: NgZone.method()
+      if (expressionText === ngZoneClassName && staticMethods.has(propertyName)) {
+        unsupportedUsages.push(node);
+      }
+
+      // Instance: zone.method() or this.zone.method()
+      if (instanceMethods.has(propertyName)) {
+        unsupportedUsages.push(node);
+      }
+    }
+    ts.forEachChild(node, visit);
+  });
+
+  return unsupportedUsages;
+}

packages/angular/cli/src/commands/mcp/tools/onpush-zoneless-migration/migrate_single_file.ts

@@ -0,0 +1,97 @@
+/**
+ * @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 { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol';
+import { ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types';
+import type { SourceFile } from 'typescript';
+import { analyzeForUnsupportedZoneUses } from './analyze_for_unsupported_zone_uses';
+import { migrateTestFile } from './migrate_test_file';
+import { generateZonelessMigrationInstructionsForComponent } from './prompts';
+import { sendDebugMessage } from './send_debug_message';
+import { getImportSpecifier, loadTypescript } from './ts_utils';
+import { MigrationResponse } from './types';
+
+export async function migrateSingleFile(
+  sourceFile: SourceFile,
+  extras: RequestHandlerExtra<ServerRequest, ServerNotification>,
+): Promise<MigrationResponse | null> {
+  const testBedSpecifier = await getImportSpecifier(sourceFile, '@angular/core/testing', 'TestBed');
+  const isTestFile = sourceFile.fileName.endsWith('.spec.ts') || !!testBedSpecifier;
+  if (isTestFile) {
+    return migrateTestFile(sourceFile);
+  }
+
+  const unsupportedZoneUseResponse = await analyzeForUnsupportedZoneUses(sourceFile);
+  if (unsupportedZoneUseResponse) {
+    return unsupportedZoneUseResponse;
+  }
+
+  let detectedStrategy: 'OnPush' | 'Default' | undefined;
+  let hasComponentDecorator = false;
+
+  const componentSpecifier = await getImportSpecifier(sourceFile, '@angular/core', 'Component');
+  if (!componentSpecifier) {
+    sendDebugMessage(`No component decorator found in file: ${sourceFile.fileName}`, extras);
+
+    return null;
+  }
+
+  const ts = await loadTypescript();
+  ts.forEachChild(sourceFile, function visit(node) {
+    if (detectedStrategy) {
+      return; // Already found, no need to traverse further
+    }
+
+    if (ts.isDecorator(node) && ts.isCallExpression(node.expression)) {
+      const callExpr = node.expression;
+      if (callExpr.expression.getText(sourceFile) === 'Component') {
+        hasComponentDecorator = true;
+        if (callExpr.arguments.length > 0 && ts.isObjectLiteralExpression(callExpr.arguments[0])) {
+          const componentMetadata = callExpr.arguments[0];
+          for (const prop of componentMetadata.properties) {
+            if (
+              ts.isPropertyAssignment(prop) &&
+              prop.name.getText(sourceFile) === 'changeDetection'
+            ) {
+              if (
+                ts.isPropertyAccessExpression(prop.initializer) &&
+                prop.initializer.expression.getText(sourceFile) === 'ChangeDetectionStrategy'
+              ) {
+                const strategy = prop.initializer.name.text;
+                if (strategy === 'OnPush' || strategy === 'Default') {
+                  detectedStrategy = strategy;
+
+                  return;
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  });
+
+  if (
+    !hasComponentDecorator ||
+    // component uses OnPush. We don't have anything more to do here.
+    detectedStrategy === 'OnPush' ||
+    // Explicit default strategy, assume there's a reason for it (already migrated, or is a library that hosts Default components) and skip.
+    detectedStrategy === 'Default'
+  ) {
+    sendDebugMessage(
+      `Component decorator found with strategy: ${detectedStrategy} in file: ${sourceFile.fileName}. Skipping migration for file.`,
+      extras,
+    );
+
+    return null;
+  }
+
+  // Component decorator found, but no change detection strategy.
+  return generateZonelessMigrationInstructionsForComponent(sourceFile.fileName);
+}

packages/angular/cli/src/commands/mcp/tools/onpush-zoneless-migration/migrate_single_file_spec.ts

@@ -0,0 +1,151 @@
+/**
+ * @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 { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol';
+import { ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types';
+import ts from 'typescript';
+import { migrateSingleFile } from './migrate_single_file';
+
+const fakeExtras = {
+  sendDebugMessage: jasmine.createSpy(),
+  sendNotification: jasmine.createSpy(),
+} as unknown as RequestHandlerExtra<ServerRequest, ServerNotification>;
+
+describe('migrateSingleFile', () => {
+  it('should identify test files by extension', async () => {
+    const fileName = 'test.spec.ts';
+    const sourceFile = ts.createSourceFile(fileName, '', ts.ScriptTarget.ESNext, true);
+
+    const result = await migrateSingleFile(sourceFile, fakeExtras);
+
+    expect(result?.content[0].text).toContain(
+      'The test file `test.spec.ts` is not yet configured for zoneless change detection.' +
+        ' You need to enable it for the entire test suite and then identify which specific tests fail.',
+    );
+  });
+
+  it('should identify test files by TestBed import', async () => {
+    const fileName = 'test.ts';
+    const content = `import { TestBed } from '@angular/core/testing';`;
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.ESNext, true);
+
+    const result = await migrateSingleFile(sourceFile, fakeExtras);
+
+    expect(result?.content[0].text).toContain(
+      'The test file `test.ts` is not yet configured for zoneless change detection.' +
+        ' You need to enable it for the entire test suite and then identify which specific tests fail.',
+    );
+  });
+
+  it('should return unsupported zone usages message if NgZone is used', async () => {
+    const fileName = 'app.component.ts';
+    const content = `
+      import { Component, NgZone } from '@angular/core';
+
+      @Component({
+        selector: 'app-root',
+        template: 'Hello',
+      })
+      export class AppComponent {
+        constructor(private zone: NgZone) {
+          this.zone.onMicrotaskEmpty(() => {});
+        }
+      }
+    `;
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.ESNext, true);
+
+    const result = await migrateSingleFile(sourceFile, fakeExtras);
+
+    expect(result?.content[0].text).toContain(
+      'The component uses NgZone APIs that are incompatible with zoneless applications',
+    );
+  });
+
+  it('should return null if component already has ChangeDetectionStrategy.OnPush', async () => {
+    const fileName = 'app.component.ts';
+    const content = `
+      import { Component, ChangeDetectionStrategy } from '@angular/core';
+
+      @Component({
+        selector: 'app-root',
+        template: 'Hello',
+        changeDetection: ChangeDetectionStrategy.OnPush,
+      })
+      export class AppComponent {}
+    `;
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.ESNext, true);
+
+    const result = await migrateSingleFile(sourceFile, fakeExtras);
+
+    expect(result).toBeNull();
+  });
+
+  it('should return null if component has ChangeDetectionStrategy.Default', async () => {
+    const fileName = 'app.component.ts';
+    const content = `
+      import { Component, ChangeDetectionStrategy } from '@angular/core';
+
+      @Component({
+        selector: 'app-root',
+        template: 'Hello',
+        changeDetection: ChangeDetectionStrategy.Default,
+      })
+      export class AppComponent {}
+    `;
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.ESNext, true);
+
+    const result = await migrateSingleFile(sourceFile, fakeExtras);
+
+    expect(result).toBeNull();
+  });
+
+  it('should return migration instructions for a component without a change detection strategy', async () => {
+    const fileName = 'app.component.ts';
+    const content = `
+      import { Component } from '@angular/core';
+
+      @Component({
+        selector: 'app-root',
+        template: 'Hello',
+      })
+      export class AppComponent {}
+    `;
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.ESNext, true);
+
+    const result = await migrateSingleFile(sourceFile, fakeExtras);
+
+    expect(result?.content[0].text).toContain(
+      'The component does not currently use a change detection strategy, which means it may rely on Zone.js',
+    );
+  });
+
+  it('should return null for a file that is not a component', async () => {
+    const fileName = 'some.service.ts';
+    const content = `
+      import { Injectable } from '@angular/core';
+
+      @Injectable({ providedIn: 'root' })
+      export class SomeService {}
+    `;
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.ESNext, true);
+
+    const result = await migrateSingleFile(sourceFile, fakeExtras);
+
+    expect(result).toBeNull();
+  });
+
+  it('should return null for an empty file', async () => {
+    const fileName = 'empty.ts';
+    const content = ``;
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.ESNext, true);
+
+    const result = await migrateSingleFile(sourceFile, fakeExtras);
+
+    expect(result).toBeNull();
+  });
+});