@stryker-mutator/core/src/di/plugin-loader.ts

The extendable JavaScript mutation testing framework

import path from 'path';
import fs from 'fs';
import { fileURLToPath, pathToFileURL, URL } from 'url';

import { Logger } from '@stryker-mutator/api/logging';
import { tokens, commonTokens, Plugin, PluginKind } from '@stryker-mutator/api/plugin';
import { notEmpty, propertyPath } from '@stryker-mutator/util';

import { fileUtils } from '../utils/file-utils.js';
import { defaultOptions } from '../config/options-validator.js';

const IGNORED_PACKAGES = ['core', 'api', 'util', 'instrumenter'];

interface PluginModule {
  strykerPlugins: Array<Plugin<PluginKind>>;
}

interface SchemaValidationContribution {
  strykerValidationSchema: Record<string, unknown>;
}

/**
 * Represents a collection of loaded plugins and metadata
 */
export interface LoadedPlugins {
  /**
   * The JSON schema contributions loaded
   */
  schemaContributions: Array<Record<string, unknown>>;
  /**
   * The actual Stryker plugins loaded, sorted by type
   */
  pluginsByKind: Map<PluginKind, Array<Plugin<PluginKind>>>;
  /**
   * The import specifiers or full URL paths to the actual plugins
   */
  pluginModulePaths: string[];
}

/**
 * Can resolve modules and pull them into memory
 */
export class PluginLoader {
  public static inject = tokens(commonTokens.logger);
  constructor(private readonly log: Logger) {}

  /**
   * Loads plugins based on configured plugin descriptors.
   * A plugin descriptor can be:
   *  * A full url: "file:///home/nicojs/github/my-plugin.js"
   *  * An absolute file path: "/home/nicojs/github/my-plugin.js"
   *  * A relative path: "./my-plugin.js"
   *  * A bare import expression: "@stryker-mutator/karma-runner"
   *  * A simple glob expression (only wild cards are supported): "@stryker-mutator/*"
   */
  public async load(pluginDescriptors: readonly string[]): Promise<LoadedPlugins> {
    const pluginModules = await this.resolvePluginModules(pluginDescriptors);
    const loadedPluginModules = (
      await Promise.all(
        pluginModules.map(async (moduleName) => {
          const plugin = await this.loadPlugin(moduleName);
          return {
            ...plugin,
            moduleName,
          };
        }),
      )
    ).filter(notEmpty);

    const result: LoadedPlugins = { schemaContributions: [], pluginsByKind: new Map<PluginKind, Array<Plugin<PluginKind>>>(), pluginModulePaths: [] };

    loadedPluginModules.forEach(({ plugins, schemaContribution, moduleName }) => {
      if (plugins) {
        result.pluginModulePaths.push(moduleName);
        plugins.forEach((plugin) => {
          const pluginsForKind = result.pluginsByKind.get(plugin.kind);
          if (pluginsForKind) {
            pluginsForKind.push(plugin);
          } else {
            result.pluginsByKind.set(plugin.kind, [plugin]);
          }
        });
      }
      if (schemaContribution) {
        result.schemaContributions.push(schemaContribution);
      }
    });
    return result;
  }

  private async resolvePluginModules(pluginDescriptors: readonly string[]): Promise<string[]> {
    return (
      await Promise.all(
        pluginDescriptors.map(async (pluginExpression) => {
          if (pluginExpression.includes('*')) {
            return await this.globPluginModules(pluginExpression);
          } else if (path.isAbsolute(pluginExpression) || pluginExpression.startsWith('.')) {
            return pathToFileURL(path.resolve(pluginExpression)).toString();
          } else {
            // Bare plugin expression like "@stryker-mutator/mocha-runner" (or file URL)
            return pluginExpression;
          }
        }),
      )
    )
      .filter(notEmpty)
      .flat();
  }

  private async globPluginModules(pluginExpression: string) {
    const { org, pkg } = parsePluginExpression(pluginExpression);

    const pluginDirectory = path.resolve(fileURLToPath(new URL('../../../../../', import.meta.url)), org);
    const regexp = new RegExp('^' + pkg.replace('*', '.*'));
    this.log.debug('Loading %s from %s', pluginExpression, pluginDirectory);
    const plugins = (await fs.promises.readdir(pluginDirectory))
      .filter((pluginName) => !IGNORED_PACKAGES.includes(pluginName) && regexp.test(pluginName))
      .map((pluginName) => `${org.length ? `${org}/` : ''}${pluginName}`);
    if (plugins.length === 0 && !defaultOptions.plugins.includes(pluginExpression)) {
      this.log.warn('Expression "%s" not resulted in plugins to load.', pluginExpression);
    }
    plugins.forEach((plugin) => this.log.debug('Loading plugin "%s" (matched with expression %s)', plugin, pluginExpression));
    return plugins;
  }

  private async loadPlugin(
    descriptor: string,
  ): Promise<{ plugins: Array<Plugin<PluginKind>> | undefined; schemaContribution: Record<string, unknown> | undefined } | undefined> {
    this.log.debug('Loading plugin %s', descriptor);
    try {
      const module = await fileUtils.importModule(descriptor);
      const plugins = isPluginModule(module) ? module.strykerPlugins : undefined;
      const schemaContribution = hasValidationSchemaContribution(module) ? module.strykerValidationSchema : undefined;
      if (plugins ?? schemaContribution) {
        return {
          plugins,
          schemaContribution,
        };
      } else {
        this.log.warn(
          'Module "%s" did not contribute a StrykerJS plugin. It didn\'t export a "%s" or "%s".',
          descriptor,
          propertyPath<PluginModule>()('strykerPlugins'),
          propertyPath<SchemaValidationContribution>()('strykerValidationSchema'),
        );
      }
    } catch (e: any) {
      if (e.code === 'ERR_MODULE_NOT_FOUND' && e.message.indexOf(descriptor) !== -1) {
        this.log.warn('Cannot find plugin "%s".\n  Did you forget to install it ?', descriptor);
      } else {
        this.log.warn('Error during loading "%s" plugin:\n  %s', descriptor, e.message);
      }
    }
    return;
  }
}

/**
 * Distills organization name from a package expression.
 * @example
 *  '@stryker-mutator/core' => { org: '@stryker-mutator', 'core' }
 *  'glob' => { org: '', 'glob' }
 */
function parsePluginExpression(pluginExpression: string) {
  const parts = pluginExpression.split('/');
  if (parts.length > 1) {
    return {
      org: parts.slice(0, parts.length - 1).join('/'),
      pkg: parts[parts.length - 1],
    };
  } else {
    return {
      org: '',
      pkg: parts[0],
    };
  }
}

function isPluginModule(module: unknown): module is PluginModule {
  const pluginModule = module as Partial<PluginModule>;
  return Array.isArray(pluginModule.strykerPlugins);
}

function hasValidationSchemaContribution(module: unknown): module is SchemaValidationContribution {
  const pluginModule = module as Partial<SchemaValidationContribution>;
  return typeof pluginModule.strykerValidationSchema === 'object';
}