@d-es-ign/stryker-js-core 9.6.0

package/src/di/plugin-loader.ts

@@ -0,0 +1,245 @@
+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';
+}

package/src/errors.ts

@@ -0,0 +1,12 @@
+import { StrykerError } from '@stryker-mutator/util';
+import { InjectionError } from 'typed-inject';
+
+export class ConfigError extends StrykerError {}
+
+export function retrieveCause(error: unknown): unknown {
+  if (error instanceof InjectionError) {
+    return error.cause;
+  } else {
+    return error;
+  }
+}

package/src/fs/file-system.ts

@@ -0,0 +1,63 @@
+import fs from 'fs';
+
+import { Task } from '@stryker-mutator/util';
+import { mergeMap, Subject } from 'rxjs';
+import { Disposable } from 'typed-inject';
+
+const MAX_CONCURRENT_FILE_IO = 256;
+
+class FileSystemAction<TOut> {
+  public readonly task = new Task<TOut>();
+
+  /**
+   * @param work The task, where a resource and input is presented
+   */
+  constructor(private readonly work: () => Promise<TOut>) {}
+
+  public async execute() {
+    try {
+      const output = await this.work();
+      this.task.resolve(output);
+    } catch (err) {
+      this.task.reject(err);
+    }
+  }
+}
+
+/**
+ * A wrapper around nodejs's 'fs' core module, for dependency injection purposes.
+ *
+ * Also has build-in buffering support with a concurrency limit (like "graceful-fs").
+ */
+export class FileSystem implements Disposable {
+  private readonly todoSubject = new Subject<FileSystemAction<any>>();
+  private readonly subscription = this.todoSubject
+    .pipe(
+      mergeMap(async (action) => {
+        await action.execute();
+      }, MAX_CONCURRENT_FILE_IO),
+    )
+    .subscribe();
+
+  public dispose(): void {
+    this.subscription.unsubscribe();
+  }
+
+  public readonly readFile = this.forward('readFile');
+  public readonly copyFile = this.forward('copyFile');
+  public readonly writeFile = this.forward('writeFile');
+  public readonly mkdir = this.forward('mkdir');
+  public readonly readdir = this.forward('readdir');
+
+  private forward<TMethod extends keyof Omit<typeof fs.promises, 'constants'>>(
+    method: TMethod,
+  ): (typeof fs.promises)[TMethod] {
+    return (...args: any[]) => {
+      const action = new FileSystemAction(() =>
+        (fs.promises[method] as any)(...args),
+      );
+      this.todoSubject.next(action);
+      return action.task.promise as any;
+    };
+  }
+}

package/src/fs/index.ts

@@ -0,0 +1,4 @@
+export * from './file-system.js';
+export * from './project.js';
+export * from './project-file.js';
+export * from './project-reader.js';

package/src/fs/project-file.ts

@@ -0,0 +1,100 @@
+import path from 'path';
+
+import { FileDescription, MutateDescription } from '@stryker-mutator/api/core';
+import { File } from '@stryker-mutator/instrumenter';
+import { I, StrykerError } from '@stryker-mutator/util';
+
+import { FileSystem } from './file-system.js';
+
+/**
+ * Represents a file inside the project under test.
+ * Has utility methods to help with copying it to the sandbox, or backing it up (when `--inPlace` is active)
+ *
+ * Assumes utf-8 as encoding when reading/writing content.
+ */
+export class ProjectFile implements FileDescription {
+  #currentContent: string | undefined;
+  #originalContent: string | undefined;
+  readonly #relativePath: string;
+
+  constructor(
+    private readonly fs: I<FileSystem>,
+    private readonly name: string,
+    public mutate: MutateDescription,
+  ) {
+    this.#relativePath = path.relative(process.cwd(), this.name);
+  }
+
+  async #writeTo(to: string): Promise<void> {
+    if (this.#currentContent === undefined) {
+      await this.fs.copyFile(this.name, to);
+    } else {
+      await this.fs.writeFile(to, this.#currentContent, 'utf-8');
+    }
+  }
+
+  public setContent(content: string): void {
+    this.#currentContent = content;
+  }
+
+  public async toInstrumenterFile(): Promise<File> {
+    return {
+      content: await this.readContent(),
+      mutate: this.mutate,
+      name: this.name,
+    };
+  }
+
+  public async readContent(): Promise<string> {
+    if (this.#currentContent === undefined) {
+      this.#currentContent = await this.readOriginal();
+    }
+    return this.#currentContent;
+  }
+
+  public async readOriginal(): Promise<string> {
+    if (this.#originalContent === undefined) {
+      try {
+        this.#originalContent = await this.fs.readFile(this.name, 'utf-8');
+      } catch (e) {
+        throw new StrykerError(`Could not read file "${this.name}"`, e);
+      }
+      if (this.#currentContent === undefined) {
+        this.#currentContent = this.#originalContent;
+      }
+    }
+    return this.#originalContent;
+  }
+
+  public async writeInPlace(): Promise<void> {
+    if (this.#currentContent !== undefined && this.hasChanges) {
+      await this.fs.writeFile(this.name, this.#currentContent, 'utf-8');
+    }
+  }
+
+  public async writeToSandbox(sandboxDir: string): Promise<string> {
+    const folderName = path.join(sandboxDir, path.dirname(this.#relativePath));
+    const targetFileName = path.join(
+      folderName,
+      path.basename(this.#relativePath),
+    );
+    await this.fs.mkdir(path.dirname(targetFileName), { recursive: true });
+    await this.#writeTo(targetFileName);
+    return targetFileName;
+  }
+
+  public async backupTo(backupDir: string): Promise<string> {
+    const backupFileName = path.join(backupDir, this.#relativePath);
+    await this.fs.mkdir(path.dirname(backupFileName), { recursive: true });
+    if (this.#originalContent === undefined) {
+      await this.fs.copyFile(this.name, backupFileName);
+    } else {
+      await this.fs.writeFile(backupFileName, this.#originalContent);
+    }
+    return backupFileName;
+  }
+
+  public get hasChanges(): boolean {
+    return this.#currentContent !== this.#originalContent;
+  }
+}