fix(schematics): keep getVertexAI rewrites on the Vertex AI backend

getAI and getVertexAI coexisted in the old vertexai module and default
to different backends: plain getAI() talks to the Gemini Developer API,
so rewriting getVertexAI as a plain rename silently moved Vertex users
onto another Google API. Rewritten calls now become
getAI(app, { backend: new VertexAIBackend(location?) }), and every
rewritten site is logged with its file and line.

Anything the migration cannot rewrite with identical semantics is left
in place with a per-site warning, and the moved import path then fails
to compile, so nothing changes behavior silently. That covers
non-literal options, getVertexAI handed around as a value or
re-exported, local declarations that shadow a rewritten name, getAI or
VertexAIBackend bound from a non AI Logic source, star re-exports,
files with syntax errors, and removed symbols with no drop-in
successor (VertexAIOptions).

Also addressed from review: an un-aliased export { X } from an old
entry point keeps the file's public export name via an alias, a root
project without a sourceRoot is walked (with a node_modules guard),
and typescript is now an optional peer resolved from the workspace at
update time, loaded after the firebase alignment so a resolution
failure costs only the rewrite. Direct firebase/vertexai imports
migrate under the same rules.

The migration is reorganized from one file into
schematics/update/v21/vertexai-to-ai/ (rename tables, shared
interfaces, compiler resolution, safety analyses, the two scan passes,
edit builders, orchestration). applyEdits is exported only so its
edit-conflict guard is unit-testable, and ngUpdate's optional compiler
parameter exists for the ESM test run, where require is unavailable.

Author: armando-navarro

docs/ai.md

@@ -8,7 +8,7 @@ Firebase AI Logic gives you access to the latest generative AI models from Googl
 
 [Learn more](https://firebase.google.com/docs/ai-logic)
 
-> Firebase AI Logic was previously called **Vertex AI in Firebase**. If you are upgrading from AngularFire 20, the module moved from `@angular/fire/vertexai` to `@angular/fire/ai` and the symbols were renamed (`getVertexAI` to `getAI`, `provideVertexAI` to `provideAI`, `VertexAI` to `AI`). Running `ng update @angular/fire` rewrites these for you. See the [AngularFire 20 to 21 upgrade guide](./version-21-upgrade.md).
+> Firebase AI Logic was previously called **Vertex AI in Firebase**. If you are upgrading from AngularFire 20, the module moved from `@angular/fire/vertexai` to `@angular/fire/ai` and most symbols were renamed (`provideVertexAI` to `provideAI`, `VertexAI` to `AI`). One is not a rename: plain `getAI()` uses the Gemini Developer API backend, so the old `getVertexAI()` maps to `getAI(app, { backend: new VertexAIBackend() })`. Running `ng update @angular/fire` rewrites all of this for you and keeps your app on the Vertex AI backend. See the [AngularFire 20 to 21 upgrade guide](./version-21-upgrade.md).
 
 ## Dependency Injection
 

docs/version-21-upgrade.md

@@ -20,14 +20,21 @@ The Vertex AI module has been renamed to Firebase AI Logic. The `@angular/fire/v
 
 | Before (`@angular/fire/vertexai`) | After (`@angular/fire/ai`) |
 |---|---|
-| `getVertexAI` | `getAI` |
+| `getVertexAI(app?, { location? })` | `getAI(app, { backend: new VertexAIBackend(location?) })` |
 | `provideVertexAI` | `provideAI` |
 | `VertexAI` | `AI` |
+| `VertexAIError` | `AIError` |
+| `VertexAIErrorCode` | `AIErrorCode` |
+| `VertexAIModel` | `AIModel` |
 | `VertexAIInstances` | `AIInstances` |
 | `vertexAIInstance$` | `AIInstance$` |
 | `VertexAIModule` | `AIModule` |
 
-`ng update @angular/fire` rewrites these imports and identifiers for you. `getGenerativeModel` and `getImagenModel` keep their names. If you import directly from the Firebase SDK, note it also renamed `firebase/vertexai` to `firebase/ai`. See [ai.md](./ai.md) for current usage.
+**`getVertexAI` is not a plain rename.** `getAI` already existed alongside it, and a plain `getAI()` call talks to the Gemini Developer API backend, not to Vertex AI. The equivalent of `getVertexAI()` is `getAI(app, { backend: new VertexAIBackend() })`, which is what the migration writes, so your app keeps calling the Vertex AI backend it was configured, enabled, and billed for. A `location` option moves into the `VertexAIBackend` constructor.
+
+`ng update @angular/fire` rewrites these imports and identifiers for you and logs every `getVertexAI` call it rewrites. Code it cannot rewrite safely (for example when the options are not a literal `{ location }` object or that literal references other rewritten symbols, when the function itself is handed around as a value, when a local declaration in the file reuses an imported symbol's name, or when the file already binds `getAI` or `VertexAIBackend` from a source other than AI Logic) is left in place with a warning. The import path itself still moves to the new entry point, so the leftover code fails to compile there, and nothing changes backends silently. A file where a named `getVertexAI` import has any use that cannot be rewritten keeps every use of its named `getVertexAI` imports in place (namespace-style `ns.getVertexAI(...)` calls are judged per call), and each skipped call is logged. `export * from '@angular/fire/vertexai'` is also left alone (rewriting it would silently rename your re-exported public symbols), so replace it with named re-exports by hand. `VertexAIOptions` was removed rather than renamed (the new `AIOptions` takes a `backend` instead of a `location`), so imports of it are left and warned about. Migrate those sites using the table above. `getGenerativeModel` and `getImagenModel` keep their names.
+
+Imports straight from the Firebase SDK (`firebase/vertexai`, gone in SDK 12) are rewritten to `firebase/ai` under the same rules. The rewrite parses your sources with the `typescript` package (an optional peer dependency of `@angular/fire`). Every Angular workspace already has it, but if the migration warns that it could not be resolved, install `typescript` and re-run. See [ai.md](./ai.md) for current usage.
 
 ## Other notes
 

src/package.json

@@ -32,11 +32,13 @@
     "@angular/platform-browser": "^21.0.0",
     "@angular/platform-server": "^21.0.0",
     "rxjs": "~7.8.0",
-    "firebase-tools": "^14.0.0 || ^15.0.0"
+    "firebase-tools": "^14.0.0 || ^15.0.0",
+    "typescript": ">=5.8 <6.0"
   },
   "peerDependenciesMeta": {
     "firebase-tools": { "optional": true },
-    "@angular/platform-server": { "optional": true }
+    "@angular/platform-server": { "optional": true },
+    "typescript": { "optional": true }
   },
   "dependencies": {
     "firebase": "^12.4.0",

src/schematics/migration.json

@@ -8,7 +8,7 @@
         },
         "migration-v21": {
             "version": "21.0.0",
-            "description": "Align the workspace's firebase dependency with the range @angular/fire 21 requires, so the install cannot contain two copies of the firebase SDK",
+            "description": "Align the workspace's firebase dependency with the range @angular/fire 21 requires, and rewrite Vertex AI imports to Firebase AI Logic (getVertexAI callers keep the Vertex AI backend)",
             "factory": "./update/v21#ngUpdate"
         },
         "ng-post-upgate": {

src/schematics/update/v21/index.jasmine.ts

@@ -1,5 +1,6 @@
 import { logging } from '@angular-devkit/core';
 import { HostTree, SchematicContext } from '@angular-devkit/schematics';
+import * as typescript from 'typescript';
 import { firebaseVersionRange } from '../../common.js';
 import { ngUpdate } from './index.js';
 import 'jasmine';
@@ -40,4 +41,45 @@ describe('migration-v21 ngUpdate', () => {
     expect(addTask).not.toHaveBeenCalled();
   });
 
+  it('keeps the firebase alignment when the rewrite throws', () => {
+    const logger = new logging.Logger('test');
+    const warn = spyOn(logger, 'warn');
+    const addTask = jasmine.createSpy('addTask');
+    const context = { logger, addTask } as unknown as SchematicContext;
+    const tree = treeWithFirebase('^11.0.0');
+    tree.create('angular.json', JSON.stringify({
+      projects: { app: { root: '', sourceRoot: 'src' } },
+    }));
+    tree.create('src/app/foo.ts', `import { getVertexAI } from '@angular/fire/vertexai';`);
+    const throwingCompiler = {
+      ScriptTarget: typescript.ScriptTarget,
+      createSourceFile: () => { throw new Error('boom'); },
+    } as unknown as typeof typescript;
+
+    ngUpdate({ compiler: throwingCompiler })(tree, context);
+
+    // The rewrite failure costs only the rewrite, never the firebase alignment.
+    const written = JSON.parse(tree.readText('package.json'));
+    expect(written.dependencies.firebase).toBe(firebaseVersionRange);
+    expect(addTask).toHaveBeenCalledTimes(1);
+    expect(warn.calls.allArgs().map(callArgs => String(callArgs[0])).join('\n'))
+      .toContain('Skipped the Vertex AI -> AI Logic source rewrite');
+  });
+
+  it('runs the Vertex AI rewrite and the alignment through one ngUpdate call', () => {
+    const { context, addTask } = contextWithTaskSpy();
+    const tree = treeWithFirebase('^11.0.0');
+    tree.create('angular.json', JSON.stringify({
+      projects: { app: { root: '', sourceRoot: 'src' } },
+    }));
+    tree.create('src/app/foo.ts', `import { getVertexAI } from '@angular/fire/vertexai';`);
+
+    ngUpdate({ compiler: typescript })(tree, context);
+
+    expect(tree.readText('src/app/foo.ts')).toBe(`import { getAI } from '@angular/fire/ai';`);
+    const written = JSON.parse(tree.readText('package.json'));
+    expect(written.dependencies.firebase).toBe(firebaseVersionRange);
+    expect(addTask).toHaveBeenCalledTimes(1);
+  });
+
 });

src/schematics/update/v21/index.ts

@@ -1,21 +1,31 @@
 import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
-// The explicit index.js subpath keeps this importable from the ESM jasmine run; the bare
+// The explicit index.js subpath keeps this importable from the ESM jasmine run. The bare
 // /tasks directory specifier only resolves under CommonJS.
 import { NodePackageInstallTask } from '@angular-devkit/schematics/tasks/index.js';
+import type * as ts from 'typescript';
 import { alignFirebaseVersion } from '../../common.js';
-import { rewriteVertexAIToAI } from './vertexai-to-ai.js';
+import { rewriteVertexAIToAI } from './vertexai-to-ai/index.js';
 
 // ng update re-runs this migration on rc-to-stable transitions (the CLI clamps the migration
 // range's upper bound to the release version), so it must stay a no-op when nothing changes.
-export const ngUpdate = (): Rule => (
+export const ngUpdate = (options?: { compiler?: typeof ts }): Rule => (
   host: Tree,
   context: SchematicContext
 ) => {
-  // Rewrite Vertex AI imports to AI Logic (source-only edits, no dependency change).
-  rewriteVertexAIToAI(host, context);
-  // Align firebase. This step changes dependencies, so only it schedules an install.
+  // Align firebase before anything else: it is the one step users cannot do without, so no
+  // failure below may cost it. This step changes dependencies, so only it schedules an install.
   if (alignFirebaseVersion(host, context)) {
     context.addTask(new NodePackageInstallTask());
   }
+  // Rewrite Vertex AI imports to AI Logic (source-only edits, no dependency change). Guarded so
+  // an unexpected rewrite failure costs only the rewrite, never the alignment above.
+  try {
+    rewriteVertexAIToAI(host, context, options?.compiler);
+  } catch (error) {
+    context.logger.warn(
+      `Skipped the Vertex AI -> AI Logic source rewrite: ${error}. ` +
+      'Any remaining @angular/fire/vertexai imports need a manual migration - see the v21 upgrade guide (docs/version-21-upgrade.md).'
+    );
+  }
   return host;
 };