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

package/src/stryker-server.ts

@@ -0,0 +1,334 @@
+import {
+  DiscoverParams,
+  DiscoverResult,
+  ConfigureParams,
+  ConfigureResult,
+  MutationTestParams,
+  MutationTestResult,
+  DiscoveredFile,
+  FileRange,
+} from 'mutation-server-protocol';
+import {
+  JSONRPCClient,
+  JSONRPCServer,
+  JSONRPCServerAndClient,
+} from 'json-rpc-2.0';
+import net from 'net';
+import { on } from 'events';
+import { createInjector, Injector } from 'typed-inject';
+import { PrepareExecutor } from './process/1-prepare-executor.js';
+import { createInstrumenter } from '@stryker-mutator/instrumenter';
+import { commonTokens, PluginKind } from '@stryker-mutator/api/plugin';
+import { coreTokens } from './di/index.js';
+import { objectUtils } from './utils/object-utils.js';
+import { JsonRpcEventDeserializer } from './utils/json-rpc-event-deserializer.js';
+import { Observable } from 'rxjs';
+import {
+  LogLevel,
+  MutantResult,
+  PartialStrykerOptions,
+} from '@stryker-mutator/api/core';
+import { Reporter } from '@stryker-mutator/api/report';
+import { Stryker } from './stryker.js';
+import { promisify } from 'util';
+import { normalizeReportFileName } from './reporters/mutation-test-report-helper.js';
+import {
+  provideLogging,
+  provideLoggingBackend,
+} from './logging/provide-logging.js';
+import {
+  LoggingBackend,
+  LoggingServer,
+  LoggingServerAddress,
+} from './logging/index.js';
+import { Logger, LoggerFactoryMethod } from '@stryker-mutator/api/logging';
+
+export const rpcMethods = Object.freeze({
+  configure: 'configure',
+  discover: 'discover',
+  mutationTest: 'mutationTest',
+  reportMutationTestProgressNotification: 'reportMutationTestProgress',
+});
+
+export interface StrykerServerOptions {
+  channel: 'stdio' | 'socket';
+  port?: number;
+  address?: string;
+}
+
+const STRYKER_SERVER_NOT_STARTED =
+  "Stryker server isn't started yet, please call `start` first";
+const STRYKER_SERVER_ALREADY_STARTED = 'Server already started';
+/**
+ * An implementation of the mutation testing server protocol for StrykerJS.
+ * - Methods: `initialize`, `discover`, `mutationTest`
+ *
+ * @see https://github.com/stryker-mutator/editor-plugins/tree/main/packages/mutation-server-protocol#readme
+ */
+export class StrykerServer {
+  #server?: net.Server;
+  #configFilePath?: string;
+  /**
+   * Keep track of the logging backend provider, so we can share the logging server between calls.
+   * New injectors for discover or mutation test tasks.
+   */
+  #loggingBackendProvider?: Injector<{
+    getLogger: LoggerFactoryMethod;
+    logger: Logger;
+    loggingSink: LoggingBackend;
+    loggingServer: LoggingServer;
+    loggingServerAddress: LoggingServerAddress;
+  }>;
+  #rootInjector?: Injector;
+  #cliOptions;
+  #injectorFactory;
+  #serverOptions;
+  #abortController = new AbortController();
+
+  /**
+   * @param cliOptions The cli options.
+   * @param serverOptions The server options.
+   * @param injectorFactory The injector factory, for testing purposes only
+   */
+  constructor(
+    serverOptions: StrykerServerOptions,
+    cliOptions: PartialStrykerOptions = {},
+    injectorFactory = createInjector,
+  ) {
+    this.#cliOptions = cliOptions;
+    this.#injectorFactory = injectorFactory;
+    this.#serverOptions = serverOptions;
+  }
+
+  /**
+   * Starts the server and listens for incoming connections.
+   * @returns The port the server is listening on, or undefined if the server is listening on stdio.
+   */
+  async start(): Promise<number | undefined> {
+    if (this.#rootInjector) {
+      throw new Error(STRYKER_SERVER_ALREADY_STARTED);
+    }
+    this.#rootInjector = this.#injectorFactory();
+    this.#loggingBackendProvider = provideLogging(
+      await provideLoggingBackend(this.#rootInjector, process.stderr),
+    );
+
+    return this.#startChannel((inStream, outStream) => {
+      const deserializer = new JsonRpcEventDeserializer();
+      const rpc = new JSONRPCServerAndClient(
+        new JSONRPCServer(),
+        new JSONRPCClient((jsonRPCRequest) => {
+          const content = Buffer.from(JSON.stringify(jsonRPCRequest));
+          outStream.write(`Content-Length: ${content.byteLength}\r\n\r\n`);
+          outStream.write(content);
+        }),
+      );
+
+      rpc.addMethod(rpcMethods.configure, this.configure.bind(this));
+      rpc.addMethod(rpcMethods.discover, this.discover.bind(this));
+      rpc.addMethod(rpcMethods.mutationTest, (params: MutationTestParams) => {
+        return new Promise<MutationTestResult>((resolve, reject) => {
+          this.mutationTest(params).subscribe({
+            next: (mutantResult) => {
+              const { fileName, ...mutant } = mutantResult;
+              rpc.client.notify(
+                rpcMethods.reportMutationTestProgressNotification,
+                {
+                  files: {
+                    [normalizeReportFileName(fileName)]: {
+                      mutants: [mutant],
+                    },
+                  },
+                } satisfies MutationTestResult,
+              );
+            },
+            error: reject,
+            complete: () => resolve({ files: {} }),
+          });
+        });
+      });
+
+      (async () => {
+        for await (const [data] of on(inStream, 'data', {
+          signal: this.#abortController.signal,
+        })) {
+          const events = deserializer.deserialize(data as Buffer);
+          for (const event of events) {
+            // https://www.npmjs.com/package/json-rpc-2.0#error-handling
+            // errors are already handled by JSON RPC, so we can ignore them here
+            void rpc.receiveAndSend(event);
+          }
+        }
+      })().catch((error) => {
+        this.#loggingBackendProvider!.resolve(commonTokens.getLogger)(
+          StrykerServer.name,
+        ).error(
+          'Error while listening for events on the JSON-RPC stream',
+          error,
+        );
+      });
+    });
+  }
+
+  /**
+   * Starts the communication channel, depending on the configured channel.
+   * @param connect A callback to connect the in- and out streams to the JSON-RPC server and client.
+   * @returns The port the server is listening on, or undefined if the server is listening on stdio.
+   */
+  async #startChannel(
+    connect: (
+      inStream: NodeJS.ReadableStream,
+      outStream: NodeJS.WritableStream,
+    ) => void,
+  ) {
+    switch (this.#serverOptions.channel) {
+      case 'stdio':
+        connect(process.stdin, process.stdout);
+        return undefined;
+      case 'socket': {
+        this.#server = net.createServer((socket) => {
+          connect(socket, socket);
+        });
+        return new Promise<number>((res) => {
+          this.#server!.listen(
+            this.#serverOptions.port,
+            this.#serverOptions.address,
+            () => {
+              res((this.#server!.address() as net.AddressInfo).port);
+            },
+          );
+        });
+      }
+    }
+  }
+
+  async stop(): Promise<void> {
+    this.#abortController.abort();
+    await this.#rootInjector?.dispose();
+    if (this.#server) {
+      await promisify(this.#server.close).bind(this.#server)();
+      this.#server = undefined;
+    }
+    this.#loggingBackendProvider = undefined;
+    this.#abortController = new AbortController();
+  }
+
+  configure(configureParams: ConfigureParams): ConfigureResult {
+    this.#configFilePath = configureParams.configFilePath;
+    return { version: '0.4.0' };
+  }
+
+  async discover(discoverParams: DiscoverParams): Promise<DiscoverResult> {
+    if (!this.#loggingBackendProvider) {
+      throw new Error(STRYKER_SERVER_NOT_STARTED);
+    }
+    const discoverInjector = this.#loggingBackendProvider.provideValue(
+      coreTokens.reporterOverride,
+      undefined,
+    );
+    try {
+      const prepareExecutor = discoverInjector.injectClass(PrepareExecutor);
+      const inj = await prepareExecutor.execute({
+        cliOptions: {
+          ...this.#cliOptions,
+          allowConsoleColors: false,
+          configFile: this.#configFilePath,
+          logLevel: LogLevel.Warning,
+        },
+        targetMutatePatterns: this.#filesToGlobPatterns(discoverParams.files),
+      });
+
+      const instrumenter = inj.injectFunction(createInstrumenter);
+      const pluginCreator = inj.resolve(coreTokens.pluginCreator);
+      const options = inj.resolve(commonTokens.options);
+      const project = inj.resolve(coreTokens.project);
+      const filesToMutate = await Promise.all(
+        [...project.filesToMutate.values()].map((file) =>
+          file.toInstrumenterFile(),
+        ),
+      );
+      const ignorers = options.ignorers.map((name) =>
+        pluginCreator.create(PluginKind.Ignore, name),
+      );
+      const instrumentResult = await instrumenter.instrument(filesToMutate, {
+        ignorers,
+        ...options.mutator,
+      });
+      const mutants = instrumentResult.mutants.map((mutant) => ({
+        ...mutant,
+        location: objectUtils.toSchemaLocation(mutant.location),
+      }));
+      const mutantsByFile = mutants.reduce((acc, mutant) => {
+        const { fileName, ...discoveredMutant } = mutant;
+        const normalizedFileName = normalizeReportFileName(fileName);
+        const file = acc.get(normalizedFileName) ?? { mutants: [] };
+        file.mutants.push(discoveredMutant);
+        acc.set(normalizedFileName, file);
+        return acc;
+      }, new Map<string, DiscoveredFile>());
+      return {
+        files: Object.fromEntries(mutantsByFile.entries()),
+      };
+    } finally {
+      await discoverInjector.dispose();
+    }
+  }
+
+  public mutationTest(
+    mutationTestParams: MutationTestParams,
+  ): Observable<MutantResult> {
+    return new Observable<MutantResult>((subscriber) => {
+      if (!this.#loggingBackendProvider) {
+        throw new Error(STRYKER_SERVER_NOT_STARTED);
+      }
+      const reporter: Reporter = {
+        onMutantTested(mutant) {
+          subscriber.next(mutant);
+        },
+      };
+
+      const runInjector = this.#loggingBackendProvider.provideValue(
+        coreTokens.reporterOverride,
+        reporter,
+      );
+      let caughtError: unknown;
+      Stryker.run(runInjector, {
+        cliOptions: {
+          ...this.#cliOptions,
+          allowConsoleColors: false,
+          configFile: this.#configFilePath,
+          logLevel: LogLevel.Warning,
+        },
+        targetMutatePatterns: this.#filesToGlobPatterns(
+          mutationTestParams.files,
+        ),
+      })
+        .catch((error) => (caughtError = error))
+        .finally(() => {
+          runInjector
+            .dispose()
+            .catch((err) => {
+              console.error('Error during dispose', err);
+            })
+            .finally(() => {
+              if (caughtError) {
+                subscriber.error(caughtError);
+              } else {
+                subscriber.complete();
+              }
+            });
+        });
+    });
+  }
+
+  #filesToGlobPatterns(files: FileRange[] | undefined): string[] | undefined {
+    return files?.map(
+      ({ path, range }) =>
+        `${path.endsWith('/') ? `${path}**/*` : path}${range ? `:${posToMutationRange(range.start)}-${posToMutationRange(range.end)}` : ''}`,
+    );
+  }
+}
+
+function posToMutationRange(pos: NonNullable<FileRange['range']>['start']) {
+  return `${pos.line}:${pos.column - 1}`; // MSP expects col-range to be exclusive, Stryker uses inclusive (https://github.com/stryker-mutator/editor-plugins/tree/main/packages/mutation-server-protocol#position-and-location-semantics)
+}

package/src/stryker.ts

@@ -0,0 +1,126 @@
+import { MutantResult, PartialStrykerOptions } from '@stryker-mutator/api/core';
+import { createInjector, Injector } from 'typed-inject';
+import { commonTokens } from '@stryker-mutator/api/plugin';
+
+import {
+  PrepareExecutor,
+  MutantInstrumenterExecutor,
+  DryRunExecutor,
+  MutationTestExecutor,
+  PrepareExecutorContext,
+  PrepareExecutorArgs,
+} from './process/index.js';
+import { coreTokens } from './di/index.js';
+import { retrieveCause, ConfigError } from './errors.js';
+import {
+  LoggingBackend,
+  provideLogging,
+  provideLoggingBackend,
+} from './logging/index.js';
+
+type MutationRunContext = PrepareExecutorContext & {
+  [coreTokens.loggingSink]: LoggingBackend;
+};
+
+/**
+ * The main Stryker class.
+ * It provides a single `runMutationTest()` function which runs mutation testing:
+ */
+export class Stryker {
+  /**
+   * @constructor
+   * @param cliOptions The cli options.
+   * @param injectorFactory The injector factory, for testing purposes only
+   */
+  constructor(
+    private readonly cliOptions: PartialStrykerOptions,
+    private readonly injectorFactory = createInjector,
+  ) {}
+
+  public async runMutationTest(): Promise<MutantResult[]> {
+    const rootInjector = this.injectorFactory();
+    try {
+      const prepareInjector = provideLogging(
+        await provideLoggingBackend(rootInjector, process.stdout),
+      ).provideValue(coreTokens.reporterOverride, undefined);
+      return await Stryker.run(prepareInjector, {
+        cliOptions: this.cliOptions,
+        targetMutatePatterns: undefined,
+      });
+    } finally {
+      await rootInjector.dispose();
+    }
+  }
+
+  /**
+   * Does the actual mutation testing.
+   * Note: this is a public static method, so it can be reused from `StrykerServer`
+   * @internal
+   */
+  static async run(
+    mutationRunInjector: Injector<MutationRunContext>,
+    args: PrepareExecutorArgs,
+  ): Promise<MutantResult[]> {
+    try {
+      // 1. Prepare. Load Stryker configuration, load the input files
+      const prepareExecutor = mutationRunInjector.injectClass(PrepareExecutor);
+      const mutantInstrumenterInjector = await prepareExecutor.execute(args);
+
+      try {
+        // 2. Mutate and instrument the files and write to the sandbox.
+        const mutantInstrumenter = mutantInstrumenterInjector.injectClass(
+          MutantInstrumenterExecutor,
+        );
+        const dryRunExecutorInjector = await mutantInstrumenter.execute();
+
+        // 3. Perform a 'dry run' (initial test run). Runs the tests without active mutants and collects coverage.
+        const dryRunExecutor =
+          dryRunExecutorInjector.injectClass(DryRunExecutor);
+        const mutationRunExecutorInjector = await dryRunExecutor.execute();
+
+        // 4. Actual mutation testing. Will check every mutant and if valid run it in an available test runner.
+        const mutationRunExecutor =
+          mutationRunExecutorInjector.injectClass(MutationTestExecutor);
+        const mutantResults = await mutationRunExecutor.execute();
+
+        return mutantResults;
+      } catch (error) {
+        if (
+          mutantInstrumenterInjector.resolve(commonTokens.options)
+            .cleanTempDir !== 'always'
+        ) {
+          const log = mutationRunInjector.resolve(commonTokens.getLogger)(
+            Stryker.name,
+          );
+          log.debug('Not removing the temp dir because an error occurred');
+          mutantInstrumenterInjector.resolve(
+            coreTokens.temporaryDirectory,
+          ).removeDuringDisposal = false;
+        }
+        throw error;
+      }
+    } catch (error) {
+      const log = mutationRunInjector.resolve(commonTokens.getLogger)(
+        Stryker.name,
+      );
+      const cause = retrieveCause(error);
+      if (cause instanceof ConfigError) {
+        log.error(cause.message);
+      } else {
+        log.error('Unexpected error occurred while running Stryker', error);
+        log.info(
+          'This might be a known problem with a solution documented in our troubleshooting guide.',
+        );
+        log.info(
+          'You can find it at https://stryker-mutator.io/docs/stryker-js/troubleshooting/',
+        );
+        if (!log.isTraceEnabled()) {
+          log.info(
+            'Still having trouble figuring out what went wrong? Try `npx stryker run --fileLogLevel trace --logLevel debug` to get some more info.',
+          );
+        }
+      }
+      throw cause;
+    }
+  }
+}

package/src/test-runner/child-process-test-runner-proxy.ts

@@ -0,0 +1,94 @@
+import { URL } from 'url';
+
+import { FileDescriptions, StrykerOptions } from '@stryker-mutator/api/core';
+import { LoggerFactoryMethod } from '@stryker-mutator/api/logging';
+import {
+  TestRunner,
+  DryRunOptions,
+  MutantRunOptions,
+  MutantRunResult,
+  DryRunResult,
+  TestRunnerCapabilities,
+} from '@stryker-mutator/api/test-runner';
+import { ExpirableTask } from '@stryker-mutator/util';
+
+import { ChildProcessCrashedError } from '../child-proxy/child-process-crashed-error.js';
+import { ChildProcessProxy } from '../child-proxy/child-process-proxy.js';
+import { LoggingServerAddress } from '../logging/index.js';
+
+import { IdGenerator } from '../child-proxy/id-generator.js';
+
+import { ChildProcessTestRunnerWorker } from './child-process-test-runner-worker.js';
+
+const MAX_WAIT_FOR_DISPOSE = 2000;
+
+/**
+ * Runs the given test runner in a child process and forwards reports about test results
+ */
+export class ChildProcessTestRunnerProxy implements TestRunner {
+  private readonly worker: ChildProcessProxy<ChildProcessTestRunnerWorker>;
+  private readonly log;
+  constructor(
+    options: StrykerOptions,
+    fileDescriptions: FileDescriptions,
+    sandboxWorkingDirectory: string,
+    loggingServerAddress: LoggingServerAddress,
+    pluginModulePaths: readonly string[],
+    getLogger: LoggerFactoryMethod,
+    idGenerator: IdGenerator,
+  ) {
+    this.log = getLogger(ChildProcessTestRunnerProxy.name);
+    this.worker = ChildProcessProxy.create(
+      new URL(
+        './child-process-test-runner-worker.js',
+        import.meta.url,
+      ).toString(),
+      loggingServerAddress,
+      options,
+      fileDescriptions,
+      pluginModulePaths,
+      sandboxWorkingDirectory,
+      ChildProcessTestRunnerWorker,
+      options.testRunnerNodeArgs,
+      getLogger,
+      idGenerator,
+    );
+  }
+
+  public capabilities(): Promise<TestRunnerCapabilities> {
+    return this.worker.proxy.capabilities();
+  }
+
+  public init(): Promise<void> {
+    return this.worker.proxy.init();
+  }
+
+  public dryRun(options: DryRunOptions): Promise<DryRunResult> {
+    return this.worker.proxy.dryRun(options);
+  }
+  public mutantRun(options: MutantRunOptions): Promise<MutantRunResult> {
+    return this.worker.proxy.mutantRun(options);
+  }
+
+  public async dispose(): Promise<void> {
+    await ExpirableTask.timeout(
+      // First let the inner test runner dispose
+      this.worker.proxy.dispose().catch((error: unknown) => {
+        // It's OK if the child process is already down.
+        if (!(error instanceof ChildProcessCrashedError)) {
+          // Handle error by logging it. We still want to kill the child process.
+          this.log.warn(
+            'An unexpected error occurred during test runner disposal. This might be worth looking into. Stryker will ignore this error.',
+            error,
+          );
+        }
+      }),
+
+      // ... but don't wait forever on that
+      MAX_WAIT_FOR_DISPOSE,
+    );
+
+    // After that, dispose the child process itself
+    await this.worker.dispose();
+  }
+}

package/src/test-runner/child-process-test-runner-worker.ts

@@ -0,0 +1,66 @@
+import { StrykerOptions } from '@stryker-mutator/api/core';
+import { commonTokens, PluginKind, tokens } from '@stryker-mutator/api/plugin';
+import {
+  TestRunner,
+  DryRunOptions,
+  MutantRunOptions,
+  MutantRunResult,
+  DryRunResult,
+  DryRunStatus,
+  MutantRunStatus,
+  TestRunnerCapabilities,
+} from '@stryker-mutator/api/test-runner';
+import { errorToString } from '@stryker-mutator/util';
+
+import { coreTokens, PluginCreator } from '../di/index.js';
+
+export class ChildProcessTestRunnerWorker implements TestRunner {
+  private readonly underlyingTestRunner: TestRunner;
+
+  public static inject = tokens(commonTokens.options, coreTokens.pluginCreator);
+  constructor({ testRunner }: StrykerOptions, pluginCreator: PluginCreator) {
+    this.underlyingTestRunner = pluginCreator.create(
+      PluginKind.TestRunner,
+      testRunner,
+    );
+  }
+
+  public async capabilities(): Promise<TestRunnerCapabilities> {
+    return this.underlyingTestRunner.capabilities();
+  }
+
+  public async init(): Promise<void> {
+    if (this.underlyingTestRunner.init) {
+      await this.underlyingTestRunner.init();
+    }
+  }
+
+  public async dispose(): Promise<void> {
+    if (this.underlyingTestRunner.dispose) {
+      await this.underlyingTestRunner.dispose();
+    }
+  }
+
+  public async dryRun(options: DryRunOptions): Promise<DryRunResult> {
+    const dryRunResult = await this.underlyingTestRunner.dryRun(options);
+    if (
+      dryRunResult.status === DryRunStatus.Complete &&
+      !dryRunResult.mutantCoverage &&
+      options.coverageAnalysis !== 'off'
+    ) {
+      // @ts-expect-error global __mutantCoverage__ isn't statically typed
+      dryRunResult.mutantCoverage = global.__mutantCoverage__;
+    }
+    if (dryRunResult.status === DryRunStatus.Error) {
+      dryRunResult.errorMessage = errorToString(dryRunResult.errorMessage);
+    }
+    return dryRunResult;
+  }
+  public async mutantRun(options: MutantRunOptions): Promise<MutantRunResult> {
+    const result = await this.underlyingTestRunner.mutantRun(options);
+    if (result.status === MutantRunStatus.Error) {
+      result.errorMessage = errorToString(result.errorMessage);
+    }
+    return result;
+  }
+}