feat(@schematics/angular): add migration to add istanbul-lib-instrument

Add a new schematic migration to automatically add istanbul-lib-instrument to devDependencies for projects that use Karma.

Covered builders:
- @angular-devkit/build-angular:karma
- @angular/build:karma
- @angular/build:unit-test (when runner is 'karma')

Author: clydin

packages/schematics/angular/migrations/add-istanbul-instrumenter/migration.ts

@@ -0,0 +1,52 @@
+/**
+ * @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 { Rule } from '@angular-devkit/schematics';
+import { DependencyType, ExistingBehavior, addDependency } from '../../utility/dependency';
+import { latestVersions } from '../../utility/latest-versions';
+import { allTargetOptions, getWorkspace } from '../../utility/workspace';
+import { Builders } from '../../utility/workspace-models';
+
+export default function (): Rule {
+  return async (tree) => {
+    const workspace = await getWorkspace(tree);
+    let needInstrumenter = false;
+
+    for (const [, project] of workspace.projects) {
+      for (const [, target] of project.targets) {
+        if (target.builder === Builders.Karma || target.builder === Builders.BuildKarma) {
+          needInstrumenter = true;
+          break;
+        }
+
+        if (target.builder === Builders.BuildUnitTest) {
+          for (const [, options] of allTargetOptions(target)) {
+            if (options['runner'] === 'karma') {
+              needInstrumenter = true;
+              break;
+            }
+          }
+        }
+
+        if (needInstrumenter) {
+          break;
+        }
+      }
+      if (needInstrumenter) {
+        break;
+      }
+    }
+
+    if (needInstrumenter) {
+      return addDependency('istanbul-lib-instrument', latestVersions['istanbul-lib-instrument'], {
+        type: DependencyType.Dev,
+        existing: ExistingBehavior.Skip,
+      });
+    }
+  };
+}

packages/schematics/angular/migrations/add-istanbul-instrumenter/migration_spec.ts

@@ -0,0 +1,103 @@
+/**
+ * @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
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { EmptyTree } from '@angular-devkit/schematics';
+import { SchematicTestRunner, UnitTestTree } from '@angular-devkit/schematics/testing';
+
+describe('Migration to add istanbul-lib-instrument', () => {
+  const schematicRunner = new SchematicTestRunner(
+    'migrations',
+    require.resolve('../migration-collection.json'),
+  );
+
+  let tree: UnitTestTree;
+  beforeEach(() => {
+    tree = new UnitTestTree(new EmptyTree());
+    tree.create(
+      '/package.json',
+      JSON.stringify({
+        devDependencies: {},
+      }),
+    );
+  });
+
+  function createWorkspace(builder: string, options?: any, configurations?: any) {
+    tree.create(
+      '/angular.json',
+      JSON.stringify({
+        version: 1,
+        projects: {
+          app: {
+            root: '',
+            targets: {
+              test: {
+                builder,
+                options,
+                configurations,
+              },
+            },
+          },
+        },
+      }),
+    );
+  }
+
+  async function expectDependency(defined: boolean) {
+    const newTree = await schematicRunner.runSchematic('add-istanbul-instrumenter', {}, tree);
+    const { devDependencies } = newTree.readJson('/package.json') as any;
+    if (defined) {
+      expect(devDependencies['istanbul-lib-instrument']).toBeDefined();
+    } else {
+      expect(devDependencies['istanbul-lib-instrument']).toBeUndefined();
+    }
+  }
+
+  it('should add istanbul-lib-instrument for @angular-devkit/build-angular:karma', async () => {
+    createWorkspace('@angular-devkit/build-angular:karma');
+
+    await expectDependency(true);
+  });
+
+  it('should add istanbul-lib-instrument for @angular/build:karma', async () => {
+    createWorkspace('@angular/build:karma');
+
+    await expectDependency(true);
+  });
+
+  it('should add istanbul-lib-instrument for @angular/build:unit-test with runner: karma', async () => {
+    createWorkspace('@angular/build:unit-test', { runner: 'karma' });
+
+    await expectDependency(true);
+  });
+
+  it('should add istanbul-lib-instrument if runner: karma is in configuration', async () => {
+    createWorkspace('@angular/build:unit-test', undefined, { ci: { runner: 'karma' } });
+
+    await expectDependency(true);
+  });
+
+  it('should NOT add istanbul-lib-instrument for @angular/build:unit-test with runner: vitest', async () => {
+    createWorkspace('@angular/build:unit-test', { runner: 'vitest' });
+
+    await expectDependency(false);
+  });
+
+  it('should NOT add istanbul-lib-instrument for @angular/build:unit-test with no runner specified (default vitest)', async () => {
+    createWorkspace('@angular/build:unit-test', {});
+
+    await expectDependency(false);
+  });
+
+  it('should NOT add istanbul-lib-instrument if no karma builder is used', async () => {
+    createWorkspace('@angular-devkit/build-angular:browser');
+
+    await expectDependency(false);
+  });
+});

packages/schematics/angular/migrations/migration-collection.json

@@ -1,6 +1,11 @@
 {
   "encapsulation": false,
   "schematics": {
+    "add-istanbul-instrumenter": {
+      "version": "22.0.0",
+      "factory": "./add-istanbul-instrumenter/migration",
+      "description": "Add istanbul-lib-instrument to devDependencies if Karma unit testing is used."
+    },
     "use-application-builder": {
       "version": "22.0.0",
       "factory": "./use-application-builder/migration",

packages/schematics/angular/utility/latest-versions/package.json

@@ -8,6 +8,7 @@
     "@types/node": "^20.17.19",
     "browser-sync": "^3.0.0",
     "express": "^5.1.0",
+    "istanbul-lib-instrument": "^6.0.3",
     "jasmine-core": "~6.1.0",
     "jasmine-spec-reporter": "~7.0.0",
     "karma-chrome-launcher": "~3.2.0",