fix(@schematics/angular): improve safety of done callback transformation

This commit adds a safety check to the `done` callback transformation in the `jasmine-vitest` schematic. Previously, if a `done` callback was used in an unhandled way (e.g., passed as an argument to a helper function), the schematic would remove the `done` parameter but leave the usage, causing runtime errors.

Now, the transformer counts the total usages of the `done` callback and compares it to the number of usages it successfully transformed. If there are unhandled usages, it aborts the transformation for that specific test and adds a TODO comment, ensuring that no broken code is generated.

(cherry picked from commit 2b99ce5)

Author: clydin

packages/schematics/angular/refactor/jasmine-vitest/transformers/jasmine-lifecycle.ts

@@ -282,6 +282,19 @@ function transformPromiseBasedDone(
   return undefined;
 }
 
+function countDoneUsages(node: ts.Node, doneIdentifier: ts.Identifier): number {
+  let count = 0;
+  const visitor = (n: ts.Node) => {
+    if (ts.isIdentifier(n) && n.text === doneIdentifier.text) {
+      count++;
+    }
+    ts.forEachChild(n, visitor);
+  };
+  ts.forEachChild(node, visitor);
+
+  return count;
+}
+
 export function transformDoneCallback(node: ts.Node, refactorCtx: RefactorContext): ts.Node {
   const { sourceFile, reporter, tsContext } = refactorCtx;
   if (
@@ -309,12 +322,17 @@ export function transformDoneCallback(node: ts.Node, refactorCtx: RefactorContex
     return node;
   }
   const doneIdentifier = doneParam.name;
+
+  // Count total usages of 'done' in the body
+  const totalUsages = countDoneUsages(functionArg.body, doneIdentifier);
+  let handledUsages = 0;
   let doneWasUsed = false;
 
   const bodyVisitor = (bodyNode: ts.Node): ts.Node | ts.Node[] | undefined => {
     const complexTransformed = transformComplexDoneCallback(bodyNode, doneIdentifier, refactorCtx);
     if (complexTransformed !== bodyNode) {
       doneWasUsed = true;
+      handledUsages++; // complex transform handles one usage
 
       return complexTransformed;
     }
@@ -330,6 +348,7 @@ export function transformDoneCallback(node: ts.Node, refactorCtx: RefactorContex
         callExpr.expression.name.text === 'fail'
       ) {
         doneWasUsed = true;
+        handledUsages++;
         reporter.reportTransformation(
           sourceFile,
           bodyNode,
@@ -350,6 +369,7 @@ export function transformDoneCallback(node: ts.Node, refactorCtx: RefactorContex
       const promiseTransformed = transformPromiseBasedDone(callExpr, doneIdentifier, refactorCtx);
       if (promiseTransformed) {
         doneWasUsed = true;
+        handledUsages++;
 
         return promiseTransformed;
       }
@@ -360,6 +380,7 @@ export function transformDoneCallback(node: ts.Node, refactorCtx: RefactorContex
         callExpr.expression.text === doneIdentifier.text
       ) {
         doneWasUsed = true;
+        handledUsages++;
 
         return ts.setTextRange(ts.factory.createEmptyStatement(), callExpr.expression);
       }
@@ -383,6 +404,20 @@ export function transformDoneCallback(node: ts.Node, refactorCtx: RefactorContex
     return bodyVisitor(node);
   });
 
+  // Safety check: if we found usages but didn't handle all of them, abort.
+  if (handledUsages < totalUsages) {
+    reporter.reportTransformation(
+      sourceFile,
+      node,
+      `Found unhandled usage of \`${doneIdentifier.text}\` callback. Skipping transformation.`,
+    );
+    const category = 'unhandled-done-usage';
+    reporter.recordTodo(category);
+    addTodoComment(node, category);
+
+    return node;
+  }
+
   if (!doneWasUsed) {
     return node;
   }

packages/schematics/angular/refactor/jasmine-vitest/transformers/jasmine-lifecycle_spec.ts

@@ -132,6 +132,7 @@ describe('Jasmine to Vitest Transformer', () => {
           });
         `,
         expected: `
+          // TODO: vitest-migration: The 'done' callback was used in an unhandled way. Please migrate manually.
           it('should not transform a function with a parameter that is not a done callback', (value) => {
             expect(value).toBe(true);
           });
@@ -157,6 +158,20 @@ describe('Jasmine to Vitest Transformer', () => {
           });
         `,
       },
+      {
+        description: 'should add a TODO for unhandled done usage',
+        input: `
+          it('should do something with helper', (done) => {
+            someHelper(done);
+          });
+        `,
+        expected: `
+          // TODO: vitest-migration: The 'done' callback was used in an unhandled way. Please migrate manually.
+          it('should do something with helper', (done) => {
+            someHelper(done);
+          });
+        `,
+      },
     ];
 
     testCases.forEach(({ description, input, expected }) => {

packages/schematics/angular/refactor/jasmine-vitest/utils/todo-notes.ts

@@ -120,6 +120,9 @@ export const TODO_NOTES = {
       ' Please refactor to access .args directly or use vi.mocked(spy).mock.lastCall.',
     url: 'https://vitest.dev/api/mocked.html#mock-lastcall',
   },
+  'unhandled-done-usage': {
+    message: "The 'done' callback was used in an unhandled way. Please migrate manually.",
+  },
 } as const;
 
 /**