refactor(@schematics/angular): implement type-safe TODO notes in jasmine-to-vitest

packages/schematics/angular/refactor/jasmine-vitest/test-file-transformer.integration_spec.ts

@@ -362,7 +362,7 @@ describe('Jasmine to Vitest Transformer - Integration Tests', () => {
         });
 
         it.skip('should handle pending tests', () => {
-          // TODO: vitest-migration: The pending() function was converted to a skipped test (\`it.skip\`).
+          // TODO: vitest-migration: The pending() function was converted to a skipped test (\`it.skip\`). See: https://vitest.dev/api/vi.html#it-skip
           // pending('This test is not yet implemented.');
         });
 
@@ -422,7 +422,7 @@ describe('Jasmine to Vitest Transformer - Integration Tests', () => {
     const vitestCode = `
       describe('Unsupported Features', () => {
         beforeAll(() => {
-          // TODO: vitest-migration: jasmine.addMatchers is not supported. Please manually migrate to expect.extend().
+          // TODO: vitest-migration: jasmine.addMatchers is not supported. Please manually migrate to expect.extend(). See: https://vitest.dev/api/expect.html#expect-extend
           jasmine.addMatchers({
             toBeAwesome: () => ({
               compare: (actual) => ({ pass: actual === 'awesome' })
@@ -437,7 +437,7 @@ describe('Jasmine to Vitest Transformer - Integration Tests', () => {
 
         it('should handle spyOnAllFunctions', () => {
           const myObj = { func1: () => {}, func2: () => {} };
-          // TODO: vitest-migration: Vitest does not have a direct equivalent for jasmine.spyOnAllFunctions(). Please spy on individual methods manually using vi.spyOn().
+          // TODO: vitest-migration: Vitest does not have a direct equivalent for jasmine.spyOnAllFunctions(). Please spy on individual methods manually using vi.spyOn(). See: https://vitest.dev/api/vi.html#vi-spyon
           jasmine.spyOnAllFunctions(myObj);
           myObj.func1();
           expect(myObj.func1).toHaveBeenCalled();

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

@@ -84,11 +84,9 @@ export function transformPending(
         bodyNode,
         'Converted `pending()` to a skipped test (`it.skip`).',
       );
-      reporter.recordTodo('pending');
-      addTodoComment(
-        replacement,
-        'The pending() function was converted to a skipped test (`it.skip`).',
-      );
+      const category = 'pending';
+      reporter.recordTodo(category);
+      addTodoComment(replacement, category);
       ts.addSyntheticLeadingComment(
         replacement,
         ts.SyntaxKind.SingleLineCommentTrivia,

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

@@ -190,8 +190,8 @@ describe('Jasmine to Vitest Transformer', () => {
         `,
         expected: `
           it.skip('is a work in progress', () => {
-              // TODO: vitest-migration: The pending() function was converted to a skipped test (\`it.skip\`).
-              // pending('Not yet implemented');
+            // TODO: vitest-migration: The pending() function was converted to a skipped test (\`it.skip\`). See: https://vitest.dev/api/vi.html#it-skip
+            // pending('Not yet implemented');
           });
         `,
       },
@@ -204,8 +204,8 @@ describe('Jasmine to Vitest Transformer', () => {
         `,
         expected: `
           it.skip('is a work in progress', function() {
-              // TODO: vitest-migration: The pending() function was converted to a skipped test (\`it.skip\`).
-              // pending('Not yet implemented');
+            // TODO: vitest-migration: The pending() function was converted to a skipped test (\`it.skip\`). See: https://vitest.dev/api/vi.html#it-skip
+            // pending('Not yet implemented');
           });
         `,
       },

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

@@ -51,22 +51,17 @@ export function transformSyntacticSugarMatchers(
   const matcherName = pae.name.text;
 
   if (matcherName === 'toHaveSpyInteractions') {
-    reporter.recordTodo('toHaveSpyInteractions');
-    addTodoComment(
-      node,
-      'Unsupported matcher ".toHaveSpyInteractions()" found. ' +
-        'Please migrate this manually by checking the `mock.calls.length` of the individual spies.',
-    );
+    const category = 'toHaveSpyInteractions';
+    reporter.recordTodo(category);
+    addTodoComment(node, category);
 
     return node;
   }
 
   if (matcherName === 'toThrowMatching') {
-    reporter.recordTodo('toThrowMatching');
-    addTodoComment(
-      node,
-      'Unsupported matcher ".toThrowMatching()" found. Please migrate this manually.',
-    );
+    const category = 'toThrowMatching';
+    reporter.recordTodo(category);
+    addTodoComment(node, category, { name: matcherName });
 
     return node;
   }
@@ -303,18 +298,13 @@ export function transformExpectAsync(
 
   if (matcherName) {
     if (matcherName === 'toBePending') {
-      reporter.recordTodo('toBePending');
-      addTodoComment(
-        node,
-        'Unsupported matcher ".toBePending()" found. Vitest does not have a direct equivalent. ' +
-          'Please migrate this manually, for example by using `Promise.race` to check if the promise settles within a short timeout.',
-      );
+      const category = 'toBePending';
+      reporter.recordTodo(category);
+      addTodoComment(node, category);
     } else {
-      reporter.recordTodo('unsupported-expect-async-matcher');
-      addTodoComment(
-        node,
-        `Unsupported expectAsync matcher ".${matcherName}()" found. Please migrate this manually.`,
-      );
+      const category = 'unsupported-expect-async-matcher';
+      reporter.recordTodo(category);
+      addTodoComment(node, category, { name: matcherName });
     }
   }
 
@@ -422,11 +412,9 @@ export function transformArrayWithExactContents(
   }
 
   if (!ts.isArrayLiteralExpression(argument.arguments[0])) {
-    reporter.recordTodo('arrayWithExactContents-dynamic-variable');
-    addTodoComment(
-      node,
-      'Cannot transform jasmine.arrayWithExactContents with a dynamic variable. Please migrate this manually.',
-    );
+    const category = 'arrayWithExactContents-dynamic-variable';
+    reporter.recordTodo(category);
+    addTodoComment(node, category);
 
     return node;
   }
@@ -617,11 +605,9 @@ export function transformExpectNothing(
   const originalText = node.getFullText().trim();
 
   reporter.reportTransformation(sourceFile, node, 'Removed `expect().nothing()` statement.');
-  reporter.recordTodo('expect-nothing');
-  addTodoComment(
-    replacement,
-    'expect().nothing() has been removed because it is redundant in Vitest. Tests without assertions pass by default.',
-  );
+  const category = 'expect-nothing';
+  reporter.recordTodo(category);
+  addTodoComment(replacement, category);
   ts.addSyntheticLeadingComment(
     replacement,
     ts.SyntaxKind.SingleLineCommentTrivia,

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

@@ -168,7 +168,7 @@ describe('Jasmine to Vitest Transformer', () => {
       {
         description: 'should add a TODO for toThrowMatching',
         input: `expect(() => {}).toThrowMatching((e) => e.message === 'foo');`,
-        expected: `// TODO: vitest-migration: Unsupported matcher ".toThrowMatching()" found. Please migrate this manually.
+        expected: `// TODO: vitest-migration: Unsupported matcher ".toThrowMatching()" found. Please migrate this manually. See: https://vitest.dev/api/expect.html#tothrowerror
 expect(() => {}).toThrowMatching((e) => e.message === 'foo');`,
       },
       {

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

@@ -18,6 +18,7 @@ import { createViCallExpression } from '../utils/ast-helpers';
 import { getJasmineMethodName, isJasmineCallExpression } from '../utils/ast-validation';
 import { addTodoComment } from '../utils/comment-helpers';
 import { RefactorContext } from '../utils/refactor-context';
+import { TodoCategory } from '../utils/todo-notes';
 
 export function transformTimerMocks(
   node: ts.Node,
@@ -140,56 +141,42 @@ export function transformGlobalFunctions(
       node,
       `Found unsupported global function \`${functionName}\`.`,
     );
-    reporter.recordTodo(functionName);
-    addTodoComment(
-      node,
-      `Unsupported global function \`${functionName}\` found. This function is used for custom reporters in Jasmine ` +
-        'and has no direct equivalent in Vitest.',
-    );
+    const category = 'unsupported-global-function';
+    reporter.recordTodo(category);
+    addTodoComment(node, category, { name: functionName });
   }
 
   return node;
 }
 
-const JASMINE_UNSUPPORTED_CALLS = new Map<string, string>([
-  [
-    'addMatchers',
-    'jasmine.addMatchers is not supported. Please manually migrate to expect.extend().',
-  ],
-  [
-    'addCustomEqualityTester',
-    'jasmine.addCustomEqualityTester is not supported. Please manually migrate to expect.addEqualityTesters().',
-  ],
-  [
-    'mapContaining',
-    'jasmine.mapContaining is not supported. Vitest does not have a built-in matcher for Maps.' +
-      ' Please manually assert the contents of the Map.',
-  ],
-  [
-    'setContaining',
-    'jasmine.setContaining is not supported. Vitest does not have a built-in matcher for Sets.' +
-      ' Please manually assert the contents of the Set.',
-  ],
+const UNSUPPORTED_JASMINE_CALLS_CATEGORIES = new Set<TodoCategory>([
+  'addMatchers',
+  'addCustomEqualityTester',
+  'mapContaining',
+  'setContaining',
 ]);
 
+// A type guard to ensure that the methodName is one of the categories handled by this transformer.
+function isUnsupportedJasmineCall(
+  methodName: string,
+): methodName is 'addMatchers' | 'addCustomEqualityTester' | 'mapContaining' | 'setContaining' {
+  return UNSUPPORTED_JASMINE_CALLS_CATEGORIES.has(methodName as TodoCategory);
+}
+
 export function transformUnsupportedJasmineCalls(
   node: ts.Node,
   { sourceFile, reporter }: RefactorContext,
 ): ts.Node {
   const methodName = getJasmineMethodName(node);
-  if (!methodName) {
-    return node;
-  }
 
-  const message = JASMINE_UNSUPPORTED_CALLS.get(methodName);
-  if (message) {
+  if (methodName && isUnsupportedJasmineCall(methodName)) {
     reporter.reportTransformation(
       sourceFile,
       node,
       `Found unsupported call \`jasmine.${methodName}\`.`,
     );
     reporter.recordTodo(methodName);
-    addTodoComment(node, message);
+    addTodoComment(node, methodName);
   }
 
   return node;
@@ -238,11 +225,9 @@ export function transformUnknownJasmineProperties(
         node,
         `Found unknown jasmine property \`jasmine.${propName}\`.`,
       );
-      reporter.recordTodo(`unknown-jasmine-property: ${propName}`);
-      addTodoComment(
-        node,
-        `Unsupported jasmine property "${propName}" found. Please migrate this manually.`,
-      );
+      const category = 'unknown-jasmine-property';
+      reporter.recordTodo(category);
+      addTodoComment(node, category, { name: propName });
     }
   }
 

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

@@ -108,7 +108,7 @@ describe('Jasmine to Vitest Transformer', () => {
           });
         `,
         expected: `
-          // TODO: vitest-migration: jasmine.addMatchers is not supported. Please manually migrate to expect.extend().
+          // TODO: vitest-migration: jasmine.addMatchers is not supported. Please manually migrate to expect.extend(). See: https://vitest.dev/api/expect.html#expect-extend
           jasmine.addMatchers({
             toBeDivisibleByTwo: function () {
               return {
@@ -141,7 +141,7 @@ describe('Jasmine to Vitest Transformer', () => {
           });
         `,
         // eslint-disable-next-line max-len
-        expected: `// TODO: vitest-migration: jasmine.addCustomEqualityTester is not supported. Please manually migrate to expect.addEqualityTesters().
+        expected: `// TODO: vitest-migration: jasmine.addCustomEqualityTester is not supported. Please manually migrate to expect.addEqualityTesters(). See: https://vitest.dev/api/expect.html#expect-addequalitytesters
           jasmine.addCustomEqualityTester((a, b) => {
             return a.toString() === b.toString();
           });

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

@@ -146,12 +146,12 @@ export function transformSpies(node: ts.Node, refactorCtx: RefactorContext): ts.
 
             return ts.factory.createCallExpression(newExpression, undefined, [arrowFunction]);
           }
-          default:
-            reporter.recordTodo('unsupported-spy-strategy');
-            addTodoComment(
-              node,
-              `Unsupported spy strategy ".and.${strategyName}()" found. Please migrate this manually.`,
-            );
+          default: {
+            const category = 'unsupported-spy-strategy';
+            reporter.recordTodo(category);
+            addTodoComment(node, category, { name: strategyName });
+            break;
+          }
         }
 
         if (newMethodName) {
@@ -184,20 +184,18 @@ export function transformSpies(node: ts.Node, refactorCtx: RefactorContext): ts.
 
       // jasmine.createSpy(name, originalFn) -> vi.fn(originalFn)
       return createViCallExpression('fn', node.arguments.length > 1 ? [node.arguments[1]] : []);
-    case 'spyOnAllFunctions':
+    case 'spyOnAllFunctions': {
       reporter.reportTransformation(
         sourceFile,
         node,
         'Found unsupported `jasmine.spyOnAllFunctions()`.',
       );
-      reporter.recordTodo('spyOnAllFunctions');
-      addTodoComment(
-        node,
-        'Vitest does not have a direct equivalent for jasmine.spyOnAllFunctions().' +
-          ' Please spy on individual methods manually using vi.spyOn().',
-      );
+      const category = 'spyOnAllFunctions';
+      reporter.recordTodo(category);
+      addTodoComment(node, category);
 
       return node;
+    }
   }
 
   return node;
@@ -218,11 +216,9 @@ export function transformCreateSpyObj(
   );
 
   if (node.arguments.length < 2) {
-    reporter.recordTodo('createSpyObj-single-argument');
-    addTodoComment(
-      node,
-      'jasmine.createSpyObj called with a single argument is not supported for transformation.',
-    );
+    const category = 'createSpyObj-single-argument';
+    reporter.recordTodo(category);
+    addTodoComment(node, category);
 
     return node;
   }
@@ -236,11 +232,9 @@ export function transformCreateSpyObj(
   } else if (ts.isObjectLiteralExpression(methods)) {
     properties = createSpyObjWithObject(methods);
   } else {
-    reporter.recordTodo('createSpyObj-dynamic-variable');
-    addTodoComment(
-      node,
-      'Cannot transform jasmine.createSpyObj with a dynamic variable. Please migrate this manually.',
-    );
+    const category = 'createSpyObj-dynamic-variable';
+    reporter.recordTodo(category);
+    addTodoComment(node, category);
 
     return node;
   }
@@ -249,11 +243,9 @@ export function transformCreateSpyObj(
     if (ts.isObjectLiteralExpression(propertiesArg)) {
       properties.push(...(propertiesArg.properties as unknown as ts.PropertyAssignment[]));
     } else {
-      reporter.recordTodo('createSpyObj-dynamic-property-map');
-      addTodoComment(
-        node,
-        'Cannot transform jasmine.createSpyObj with a dynamic property map. Please migrate this manually.',
-      );
+      const category = 'createSpyObj-dynamic-property-map';
+      reporter.recordTodo(category);
+      addTodoComment(node, category);
     }
   }
 
@@ -426,12 +418,9 @@ export function transformSpyCallInspection(
             !ts.isIdentifier(node.parent.name) ||
             node.parent.name.text !== 'args'
           ) {
-            reporter.recordTodo('mostRecent-without-args');
-            addTodoComment(
-              node,
-              'Direct usage of mostRecent() is not supported.' +
-                ' Please refactor to access .args directly or use vi.mocked(spy).mock.lastCall.',
-            );
+            const category = 'mostRecent-without-args';
+            reporter.recordTodo(category);
+            addTodoComment(node, category);
           }
 
           return node;