refactor(@schematics/angular): add Karma configuration analyzer and comparer

Introduces a new utility for analyzing and comparing Karma configuration files. This is a foundational step for migrating from Karma to other testing frameworks like Jest and Vitest, as it allows the migration schematic to understand the user's existing setup.

The new `analyzeKarmaConfig` function uses TypeScript's AST parser to safely extract settings from a `karma.conf.js` file. It can identify common patterns, including `require` calls, and flags configurations that are too complex for static analysis.

The `compareKarmaConfigs` function provides the ability to diff a user's Karma configuration against a default template. This will be used to determine which custom settings need to be migrated.

Known limitations of the analyzer:
- It does not resolve variables or complex expressions. Any value that is not a literal (string, number, boolean, array, object) or a direct `require` call will be marked as an unsupported value.
- It does not support Karma configuration files that use ES Modules (import/export syntax).

Author: clydin

packages/schematics/angular/migrations/karma/karma-config-analyzer.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 ts from '../../third_party/github.com/Microsoft/TypeScript/lib/typescript';
+
+export interface RequireInfo {
+  module: string;
+  export?: string;
+  isCall?: boolean;
+  arguments?: KarmaConfigValue[];
+}
+
+export type KarmaConfigValue =
+  | string
+  | boolean
+  | number
+  | KarmaConfigValue[]
+  | { [key: string]: KarmaConfigValue }
+  | RequireInfo
+  | undefined;
+
+export interface KarmaConfigAnalysis {
+  settings: Map<string, KarmaConfigValue>;
+  hasUnsupportedValues: boolean;
+}
+
+function isRequireInfo(value: KarmaConfigValue): value is RequireInfo {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) && 'module' in value;
+}
+
+/**
+ * Analyzes the content of a Karma configuration file to extract its settings.
+ *
+ * @param content The string content of the `karma.conf.js` file.
+ * @returns An object containing the configuration settings and a flag indicating if unsupported values were found.
+ */
+export function analyzeKarmaConfig(content: string): KarmaConfigAnalysis {
+  const sourceFile = ts.createSourceFile('karma.conf.js', content, ts.ScriptTarget.Latest, true);
+  const settings = new Map<string, KarmaConfigValue>();
+  let hasUnsupportedValues = false;
+
+  function visit(node: ts.Node) {
+    // The Karma configuration is defined within a `config.set({ ... })` call.
+    if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression) &&
+      node.expression.expression.getText(sourceFile) === 'config' &&
+      node.expression.name.text === 'set' &&
+      node.arguments.length === 1 &&
+      ts.isObjectLiteralExpression(node.arguments[0])
+    ) {
+      // We found `config.set`, now we extract the properties from the object literal.
+      for (const prop of node.arguments[0].properties) {
+        if (
+          ts.isPropertyAssignment(prop) &&
+          (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name))
+        ) {
+          const key = prop.name.text;
+          const value = extractValue(prop.initializer);
+          settings.set(key, value);
+        }
+      }
+    } else {
+      ts.forEachChild(node, visit);
+    }
+  }
+
+  function extractValue(node: ts.Expression): KarmaConfigValue {
+    if (ts.isStringLiteral(node)) {
+      return node.text;
+    }
+    if (ts.isNumericLiteral(node)) {
+      return Number(node.text);
+    }
+    if (node.kind === ts.SyntaxKind.TrueKeyword) {
+      return true;
+    }
+    if (node.kind === ts.SyntaxKind.FalseKeyword) {
+      return false;
+    }
+    if (ts.isIdentifier(node) && (node.text === '__dirname' || node.text === '__filename')) {
+      return node.text;
+    }
+
+    if (ts.isCallExpression(node)) {
+      // Handle require('...')
+      if (
+        ts.isIdentifier(node.expression) &&
+        node.expression.text === 'require' &&
+        node.arguments.length === 1 &&
+        ts.isStringLiteral(node.arguments[0])
+      ) {
+        return { module: node.arguments[0].text };
+      }
+
+      // Handle calls on a require, e.g. require('path').join()
+      const calleeValue = extractValue(node.expression);
+      if (isRequireInfo(calleeValue)) {
+        return {
+          ...calleeValue,
+          isCall: true,
+          arguments: node.arguments.map(extractValue),
+        };
+      }
+    }
+
+    // Handle require('...').someExport
+    if (ts.isPropertyAccessExpression(node)) {
+      const value = extractValue(node.expression);
+      if (isRequireInfo(value)) {
+        const currentExport = value.export ? `${value.export}.${node.name.text}` : node.name.text;
+
+        return { ...value, export: currentExport };
+      }
+    }
+
+    if (ts.isArrayLiteralExpression(node)) {
+      return node.elements.map(extractValue);
+    }
+    if (ts.isObjectLiteralExpression(node)) {
+      const obj: { [key: string]: KarmaConfigValue } = {};
+      for (const prop of node.properties) {
+        if (
+          ts.isPropertyAssignment(prop) &&
+          (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name))
+        ) {
+          // Recursively extract values for nested objects.
+          obj[prop.name.text] = extractValue(prop.initializer);
+        } else {
+          hasUnsupportedValues = true;
+        }
+      }
+
+      return obj;
+    }
+    // For complex expressions (like variables) that we don't need to resolve,
+    // we mark the analysis as potentially incomplete.
+    hasUnsupportedValues = true;
+
+    return undefined;
+  }
+
+  visit(sourceFile);
+
+  return { settings, hasUnsupportedValues };
+}

packages/schematics/angular/migrations/karma/karma-config-analyzer_spec.ts

@@ -0,0 +1,229 @@
+/**
+ * @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 { RequireInfo, analyzeKarmaConfig } from './karma-config-analyzer';
+import { generateDefaultKarmaConfig } from './karma-config-comparer';
+
+describe('Karma Config Analyzer', () => {
+  it('should parse a basic karma config file', () => {
+    const karmaConf = `
+      module.exports = function (config) {
+        config.set({
+          basePath: '',
+          frameworks: ['jasmine', '@angular-devkit/build-angular'],
+          plugins: [
+            require('karma-jasmine'),
+            require('karma-chrome-launcher'),
+            require('karma-jasmine-html-reporter'),
+            require('karma-coverage'),
+            require('@angular-devkit/build-angular/plugins/karma'),
+          ],
+          client: {
+            clearContext: false, // leave Jasmine Spec Runner output visible in browser
+          },
+          jasmineHtmlReporter: {
+            suppressAll: true, // removes the duplicated traces
+          },
+          coverageReporter: {
+            dir: require('path').join(__dirname, './coverage/test-project'),
+            subdir: '.',
+            reporters: [{ type: 'html' }, { type: 'text-summary' }],
+          },
+          reporters: ['progress', 'kjhtml'],
+          port: 9876,
+          colors: true,
+          logLevel: config.LOG_INFO,
+          autoWatch: true,
+          browsers: ['Chrome'],
+          singleRun: false,
+          restartOnFileChange: true,
+        });
+      };
+    `;
+
+    const { settings, hasUnsupportedValues } = analyzeKarmaConfig(karmaConf);
+
+    expect(settings.get('basePath') as unknown).toBe('');
+    expect(settings.get('frameworks') as unknown).toEqual([
+      'jasmine',
+      '@angular-devkit/build-angular',
+    ]);
+    expect(settings.get('port') as unknown).toBe(9876);
+    expect(settings.get('autoWatch') as boolean).toBe(true);
+    expect(settings.get('singleRun') as boolean).toBe(false);
+    expect(settings.get('reporters') as unknown).toEqual(['progress', 'kjhtml']);
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const plugins = settings.get('plugins') as any[];
+    expect(plugins).toBeInstanceOf(Array);
+    expect(plugins.length).toBe(5);
+    expect(plugins[0]).toEqual({ module: 'karma-jasmine' });
+    expect(plugins[4]).toEqual({ module: '@angular-devkit/build-angular/plugins/karma' });
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const coverageReporter = settings.get('coverageReporter') as any;
+    const dirInfo = coverageReporter.dir as RequireInfo;
+    expect(dirInfo.module).toBe('path');
+    expect(dirInfo.export).toBe('join');
+    expect(dirInfo.isCall).toBe(true);
+    expect(dirInfo.arguments as unknown).toEqual(['__dirname', './coverage/test-project']);
+
+    // config.LOG_INFO is a variable, so it should be flagged as unsupported
+    expect(hasUnsupportedValues).toBe(true);
+  });
+
+  it('should return an empty map for an empty config file', () => {
+    const { settings, hasUnsupportedValues } = analyzeKarmaConfig('');
+
+    expect(settings.size).toBe(0);
+    expect(hasUnsupportedValues).toBe(false);
+  });
+
+  it('should handle a config file with no config.set call', () => {
+    const karmaConf = `
+      module.exports = function (config) {
+        // No config.set call
+      };
+    `;
+    const { settings, hasUnsupportedValues } = analyzeKarmaConfig(karmaConf);
+
+    expect(settings.size).toBe(0);
+    expect(hasUnsupportedValues).toBe(false);
+  });
+
+  it('should detect unsupported values like variables', () => {
+    const karmaConf = `
+      const myBrowsers = ['Chrome', 'Firefox'];
+      module.exports = function (config) {
+        config.set({
+          browsers: myBrowsers,
+        });
+      };
+    `;
+    const { settings, hasUnsupportedValues } = analyzeKarmaConfig(karmaConf);
+
+    expect(settings.get('browsers')).toBeUndefined();
+    expect(hasUnsupportedValues).toBe(true);
+  });
+
+  it('should correctly parse require with nested exports', () => {
+    const karmaConf = `
+      module.exports = function (config) {
+        config.set({
+          reporter: require('some-plugin').reporter.type,
+        });
+      };
+    `;
+    const { settings, hasUnsupportedValues } = analyzeKarmaConfig(karmaConf);
+
+    const reporter = settings.get('reporter') as RequireInfo;
+    expect(reporter.module).toBe('some-plugin');
+    expect(reporter.export).toBe('reporter.type');
+    expect(hasUnsupportedValues).toBe(false);
+  });
+
+  it('should handle an array with mixed values', () => {
+    const karmaConf = `
+      module.exports = function (config) {
+        config.set({
+          plugins: [
+            'karma-jasmine',
+            require('karma-chrome-launcher'),
+            true,
+          ],
+        });
+      };
+    `;
+    const { settings, hasUnsupportedValues } = analyzeKarmaConfig(karmaConf);
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const plugins = settings.get('plugins') as any[];
+    expect(plugins).toEqual(['karma-jasmine', { module: 'karma-chrome-launcher' }, true]);
+    expect(hasUnsupportedValues).toBe(false);
+  });
+
+  it('should not report unsupported values when all values are literals or requires', () => {
+    const karmaConf = `
+      module.exports = function (config) {
+        config.set({
+          autoWatch: true,
+          browsers: ['Chrome'],
+          plugins: [require('karma-jasmine')],
+        });
+      };
+    `;
+    const { hasUnsupportedValues } = analyzeKarmaConfig(karmaConf);
+
+    expect(hasUnsupportedValues).toBe(false);
+  });
+
+  it('should handle path.join with variables and flag as unsupported', () => {
+    const karmaConf = `
+      const myPath = './coverage/test-project';
+      module.exports = function (config) {
+        config.set({
+          coverageReporter: {
+            dir: require('path').join(__dirname, myPath),
+          },
+        });
+      };
+    `;
+    const { settings, hasUnsupportedValues } = analyzeKarmaConfig(karmaConf);
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const coverageReporter = settings.get('coverageReporter') as any;
+    const dirInfo = coverageReporter.dir as RequireInfo;
+    expect(dirInfo.module).toBe('path');
+    expect(dirInfo.export).toBe('join');
+    expect(dirInfo.isCall).toBe(true);
+    expect(dirInfo.arguments as unknown).toEqual(['__dirname', undefined]); // myPath is a variable
+    expect(hasUnsupportedValues).toBe(true);
+  });
+
+  it('should correctly parse the default karma config template', async () => {
+    const defaultConfig = await generateDefaultKarmaConfig('..', 'test-project', true);
+    const { settings, hasUnsupportedValues } = analyzeKarmaConfig(defaultConfig);
+
+    expect(hasUnsupportedValues).toBe(false);
+    expect(settings.get('basePath') as unknown).toBe('');
+    expect(settings.get('frameworks') as unknown).toEqual([
+      'jasmine',
+      '@angular-devkit/build-angular',
+    ]);
+    expect(settings.get('plugins') as unknown).toEqual([
+      { module: 'karma-jasmine' },
+      { module: 'karma-chrome-launcher' },
+      { module: 'karma-jasmine-html-reporter' },
+      { module: 'karma-coverage' },
+      { module: '@angular-devkit/build-angular/plugins/karma' },
+    ]);
+    expect(settings.get('client') as unknown).toEqual({
+      jasmine: {},
+    });
+    expect(settings.get('jasmineHtmlReporter') as unknown).toEqual({
+      suppressAll: true,
+    });
+    const coverageReporter = settings.get('coverageReporter') as {
+      dir: RequireInfo;
+      subdir: string;
+      reporters: { type: string }[];
+    };
+    expect(coverageReporter.dir.module).toBe('path');
+    expect(coverageReporter.dir.export).toBe('join');
+    expect(coverageReporter.dir.isCall).toBe(true);
+    expect(coverageReporter.dir.arguments as unknown).toEqual([
+      '__dirname',
+      '../coverage/test-project',
+    ]);
+    expect(coverageReporter.subdir).toBe('.');
+    expect(coverageReporter.reporters).toEqual([{ type: 'html' }, { type: 'text-summary' }]);
+    expect(settings.get('reporters') as unknown).toEqual(['progress', 'kjhtml']);
+    expect(settings.get('browsers') as unknown).toEqual(['Chrome']);
+    expect(settings.get('restartOnFileChange') as unknown).toBe(true);
+  });
+});