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

package/src/check/check-status.ts

@@ -0,0 +1,4 @@
+export enum CheckStatus {
+  Passed = 'passed',
+  CompileError = 'compileError',
+}

package/src/check/checker.ts

@@ -0,0 +1,22 @@
+import { Mutant } from '../core/index.js';
+
+import { CheckResult } from './check-result.js';
+
+export interface Checker {
+  init(): Promise<void>;
+
+  /**
+   * Check a mutant group.
+   * @param mutants A group of mutants to check
+   * @returns key-value pairs of mutant ids with the check results
+   */
+  check(mutants: Mutant[]): Promise<Record<string, CheckResult>>;
+
+  /**
+   * Group mutants into groups to check.
+   * If missing, groups of singular mutants are assumed.
+   * @param mutants the mutants to group
+   * @returns the groups of mutant ids
+   */
+  group?(mutants: Mutant[]): Promise<string[][]>;
+}

package/src/check/index.ts

@@ -0,0 +1,3 @@
+export * from './checker.js';
+export * from './check-result.js';
+export * from './check-status.js';

package/src/check/mutant-status.ts

@@ -0,0 +1,10 @@
+export enum MutantStatus {
+  Init = 'init',
+  Ignored = 'ignored',
+  NoCoverage = 'noCoverage',
+  Killed = 'killed',
+  Survived = 'survived',
+  TimedOut = 'timedOut',
+  RuntimeError = 'runtimeError',
+  CompileError = 'compileError',
+}

package/src/core/file-description.ts

@@ -0,0 +1,15 @@
+import { MutationRange } from './mutation-range.js';
+
+/**
+ * Input files by file name.
+ */
+export type FileDescriptions = Record<string, FileDescription>;
+
+export type MutateDescription = MutationRange[] | boolean;
+
+/**
+ * The metadata of a input file
+ */
+export interface FileDescription {
+  mutate: MutateDescription;
+}

package/src/core/index.ts

@@ -0,0 +1,16 @@
+export type { Position } from './position.js';
+export type { Location } from './location.js';
+export * from './mutant.js';
+export * from '../../src-generated/stryker-core.js';
+export * from './report-types.js';
+export * from './stryker-options-schema.js';
+export * from './partial-stryker-options.js';
+export * from './instrument.js';
+export * from './mutant-coverage.js';
+export * from './mutant-test-plan.js';
+export * from './file-description.js';
+export * from './mutation-range.js';
+/**
+ * Re-export all members from "mutation-testing-report-schema" under the `schema` key
+ */
+export * as schema from 'mutation-testing-report-schema/api';

package/src/core/instrument.ts

@@ -0,0 +1,26 @@
+import { MutantCoverage } from './mutant-coverage.js';
+
+/**
+ * Identifiers used when instrumenting the code
+ */
+export const INSTRUMENTER_CONSTANTS = Object.freeze({
+  NAMESPACE: '__stryker__',
+  MUTATION_COVERAGE_OBJECT: identity('mutantCoverage'),
+  ACTIVE_MUTANT: identity('activeMutant'),
+  CURRENT_TEST_ID: identity('currentTestId'),
+  HIT_COUNT: identity('hitCount'),
+  HIT_LIMIT: identity('hitLimit'),
+  ACTIVE_MUTANT_ENV_VARIABLE: '__STRYKER_ACTIVE_MUTANT__',
+} as const);
+
+export interface InstrumenterContext {
+  activeMutant?: string;
+  currentTestId?: string;
+  mutantCoverage?: MutantCoverage;
+  hitCount?: number;
+  hitLimit?: number;
+}
+
+function identity<T extends keyof InstrumenterContext>(key: T): T {
+  return key;
+}

package/src/core/location.ts

@@ -0,0 +1,9 @@
+import { Position } from './position.js';
+
+/**
+ * A location in the source code which can span multiple lines and/or columns.
+ */
+export interface Location {
+  start: Position;
+  end: Position;
+}

package/src/core/mutant-coverage.ts

@@ -0,0 +1,11 @@
+export interface MutantCoverage {
+  static: CoverageData;
+  perTest: CoveragePerTestId;
+}
+
+export type CoveragePerTestId = Record<string, CoverageData>;
+
+/**
+ * Keys are mutant ids, the numbers are the amount of times it was hit.
+ */
+export type CoverageData = Record<string, number>;

package/src/core/mutant-test-plan.ts

@@ -0,0 +1,56 @@
+import * as schema from 'mutation-testing-report-schema/api';
+
+import { MutantRunOptions } from '../test-runner/index.js';
+
+import { MutantTestCoverage } from './mutant.js';
+
+/**
+ * Represents a plan to test a mutant. Can either be an early result (an ignored mutant for example) or a plan to test a mutant in a test runner
+ */
+export type MutantTestPlan = MutantEarlyResultPlan | MutantRunPlan;
+
+/**
+ * The test plans that belong to a mutant.
+ */
+export enum PlanKind {
+  /**
+   * Early result plan, mutant does not have to be checked or run.
+   */
+  EarlyResult = 'EarlyResult',
+  /**
+   * Run plan, mutant will have to be checked and run.
+   */
+  Run = 'Run',
+}
+
+/**
+ * Represents an mutant early result plan.
+ */
+export interface MutantEarlyResultPlan {
+  plan: PlanKind.EarlyResult;
+  /**
+   * The mutant that already has a final status.
+   */
+  mutant: MutantTestCoverage & { status: schema.MutantStatus };
+}
+
+/**
+ * Represents a mutant test plan.
+ */
+export interface MutantRunPlan {
+  plan: PlanKind.Run;
+  /**
+   * The mutant that has to be tested.
+   */
+  mutant: MutantTestCoverage;
+  /**
+   * The run options that will be used to test this mutant
+   */
+  runOptions: MutantRunOptions;
+
+  /**
+   * Estimated net time to run this mutant when it would survive in ms (which should be the worst case).
+   * This is used as input to calculate the runOptions.timeout
+   */
+  netTime: number;
+}

package/src/core/mutant.ts

@@ -0,0 +1,54 @@
+import * as schema from 'mutation-testing-report-schema/api';
+import type { MutantRunExecutedTest } from '../test-runner/index.js';
+
+export type { MutantStatus } from 'mutation-testing-report-schema/api';
+
+// We're reusing the `MutantResult` interface here to acquire uniformity.
+
+/**
+ * Represents a mutant in its initial state.
+ */
+export interface Mutant extends Pick<
+  schema.MutantResult,
+  | 'coveredBy'
+  | 'id'
+  | 'killedBy'
+  | 'location'
+  | 'mutatorName'
+  | 'replacement'
+  | 'static'
+  | 'statusReason'
+  | 'testsCompleted'
+> {
+  /**
+   * The file name from which this mutant originated
+   */
+  fileName: string;
+  /**
+   * Actual mutation that has been applied.
+   */
+  replacement: string;
+  /**
+   * The status of a mutant if known. This should be undefined for a mutant that still needs testing.
+   */
+  status?: schema.MutantStatus;
+}
+
+/**
+ * Represents a mutant in its matched-with-the-tests state, ready to be tested.
+ */
+export type MutantTestCoverage = Mutant &
+  Pick<schema.MutantResult, 'coveredBy' | 'static'>;
+
+/**
+ * Represents a mutant in its final state, ready to be reported.
+ */
+export type MutantResult = Mutant &
+  schema.MutantResult & {
+    /**
+     * Optional per-test timing details captured during mutation runs.
+     * This field is for runtime/reporter diagnostics and is not part of the
+     * mutation-testing-report-schema payload.
+     */
+    executedTests?: MutantRunExecutedTest[];
+  };

package/src/core/mutation-range.ts

@@ -0,0 +1,16 @@
+import { Position } from './position.js';
+
+/**
+ * Represents a range of mutants that the instrumenter should instrument
+ */
+export interface MutationRange {
+  /**
+   * The start of the range to instrument, by line and column number, inclusive
+   */
+  start: Position;
+
+  /**
+   * The end of the range to instrument, by line and number, inclusive
+   */
+  end: Position;
+}

package/src/core/partial-stryker-options.ts

@@ -0,0 +1,14 @@
+import { StrykerOptions } from '../../src-generated/stryker-core.js';
+
+/**
+ * When configuring stryker, every option is optional
+ * Including deep properties like `dashboard.project`.
+ * That's why we use a `DeepPartial` mapped type here.
+ */
+export type PartialStrykerOptions = DeepPartial<StrykerOptions>;
+
+type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends Record<string, any>
+    ? DeepPartial<T[P]> | undefined
+    : T[P];
+};

package/src/core/position.ts

@@ -0,0 +1,8 @@
+/**
+ * A specific spot in the source code based on line and column.
+ * Stryker uses zero-based indexes. So the first character in a file is at line 0, column 0.
+ */
+export interface Position {
+  line: number;
+  column: number;
+}

package/src/core/report-types.ts

@@ -0,0 +1,6 @@
+import { ReportType } from '../../src-generated/stryker-core.js';
+
+export const ALL_REPORT_TYPES = Object.freeze([
+  ReportType.Full,
+  ReportType.MutationScore,
+]);

package/src/core/stryker-options-schema.ts

@@ -0,0 +1,11 @@
+import { readFileSync } from 'fs';
+import { URL } from 'url';
+
+const strykerCoreSchema: Record<string, unknown> = JSON.parse(
+  readFileSync(
+    new URL('../../schema/stryker-core.json', import.meta.url),
+    'utf-8',
+  ),
+);
+
+export { strykerCoreSchema };

package/src/ignore/ignorer.ts

@@ -0,0 +1,8 @@
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface NodePath {
+  // Left empty so the declaration can be merged
+}
+
+export interface Ignorer {
+  shouldIgnore(path: NodePath): string | undefined;
+}

package/src/ignore/index.ts

@@ -0,0 +1 @@
+export * from './ignorer.js';

package/src/logging/index.ts

@@ -0,0 +1,2 @@
+export type { Logger } from './logger.js';
+export type { LoggerFactoryMethod } from './logger-factory-method.js';

package/src/logging/logger-factory-method.ts

@@ -0,0 +1,10 @@
+import { Logger } from './logger.js';
+
+/**
+ * Represents a factory to get loggers by category name.
+ * This interface is used to describe the shape of a logger factory method.
+ *
+ * @param   {String} [categoryName] name of category to log to.
+ * @returns {Logger} instance of logger for the category
+ */
+export type LoggerFactoryMethod = (categoryName?: string) => Logger;

package/src/logging/logger.ts

@@ -0,0 +1,15 @@
+export interface Logger {
+  isTraceEnabled(): boolean;
+  isDebugEnabled(): boolean;
+  isInfoEnabled(): boolean;
+  isWarnEnabled(): boolean;
+  isErrorEnabled(): boolean;
+  isFatalEnabled(): boolean;
+
+  trace(message: string, ...args: any[]): void;
+  debug(message: string, ...args: any[]): void;
+  info(message: string, ...args: any[]): void;
+  warn(message: string, ...args: any[]): void;
+  error(message: string, ...args: any[]): void;
+  fatal(message: string, ...args: any[]): void;
+}

package/src/plugin/contexts.ts

@@ -0,0 +1,21 @@
+import { FileDescriptions, StrykerOptions } from '../core/index.js';
+import { Logger, LoggerFactoryMethod } from '../logging/index.js';
+
+import { commonTokens } from './tokens.js';
+
+/**
+ * The basic dependency injection context within Stryker
+ */
+export interface BaseContext {
+  [commonTokens.getLogger]: LoggerFactoryMethod;
+  [commonTokens.logger]: Logger;
+}
+
+/**
+ * The dependency injection context for most of Stryker's plugins.
+ * Can inject basic stuff as well as the Stryker options
+ */
+export interface PluginContext extends BaseContext {
+  [commonTokens.options]: StrykerOptions;
+  [commonTokens.fileDescriptions]: FileDescriptions;
+}

package/src/plugin/index.ts

@@ -0,0 +1,12 @@
+export * from './contexts.js';
+export * from './plugins.js';
+export * from './plugin-kind.js';
+export * from './tokens.js';
+export * from './scope.js';
+export type {
+  Injectable,
+  Injector,
+  InjectionToken,
+  CorrespondingType,
+  Disposable,
+} from 'typed-inject';

package/src/plugin/plugin-kind.ts

@@ -0,0 +1,9 @@
+/**
+ * The plugin kinds supported by Stryker
+ */
+export enum PluginKind {
+  Checker = 'Checker',
+  TestRunner = 'TestRunner',
+  Reporter = 'Reporter',
+  Ignore = 'Ignore',
+}

package/src/plugin/plugins.ts

@@ -0,0 +1,155 @@
+import type {
+  InjectableClass,
+  InjectableFunction,
+  InjectionToken,
+} from 'typed-inject';
+
+import { Reporter } from '../report/index.js';
+import { TestRunner } from '../test-runner/index.js';
+import { Checker } from '../check/index.js';
+
+import { Ignorer } from '../ignore/ignorer.js';
+
+import { PluginContext } from './contexts.js';
+import { PluginKind } from './plugin-kind.js';
+
+/**
+ * Represents a StrykerPlugin
+ */
+export type Plugin<TPluginKind extends PluginKind> =
+  | ClassPlugin<TPluginKind, Array<InjectionToken<PluginContext>>>
+  | FactoryPlugin<TPluginKind, Array<InjectionToken<PluginContext>>>
+  | ValuePlugin<TPluginKind>;
+
+/**
+ * Represents a plugin that is created with a factory method
+ */
+export interface FactoryPlugin<
+  TPluginKind extends PluginKind,
+  Tokens extends Array<InjectionToken<PluginContext>>,
+> {
+  readonly kind: TPluginKind;
+  readonly name: string;
+  /**
+   * The factory method used to create the plugin
+   */
+  readonly factory: InjectableFunction<
+    PluginContext,
+    PluginInterfaces[TPluginKind],
+    Tokens
+  >;
+}
+
+/**
+ * Represents a plugin that is provided as a simple value.
+ */
+export interface ValuePlugin<TPluginKind extends PluginKind> {
+  readonly kind: TPluginKind;
+  readonly name: string;
+  readonly value: PluginInterfaces[TPluginKind];
+}
+
+/**
+ * Represents a plugin that is created by instantiating a class.
+ */
+export interface ClassPlugin<
+  TPluginKind extends PluginKind,
+  Tokens extends Array<InjectionToken<PluginContext>>,
+> {
+  readonly kind: TPluginKind;
+  readonly name: string;
+  /**
+   * The prototype function (class) used to create the plugin.
+   * Not called `class` here, because that is a keyword
+   */
+  readonly injectableClass: InjectableClass<
+    PluginContext,
+    PluginInterfaces[TPluginKind],
+    Tokens
+  >;
+}
+
+/**
+ * Declare a class plugin. Use this method in order to type check the dependency graph of your plugin
+ * @param kind The plugin kind
+ * @param name The name of the plugin
+ * @param injectableClass The class to be instantiated for the plugin
+ */
+export function declareClassPlugin<
+  TPluginKind extends PluginKind,
+  Tokens extends Array<InjectionToken<PluginContext>>,
+>(
+  kind: TPluginKind,
+  name: string,
+  injectableClass: InjectableClass<
+    PluginContext,
+    PluginInterfaces[TPluginKind],
+    Tokens
+  >,
+): ClassPlugin<TPluginKind, Tokens> {
+  return {
+    injectableClass,
+    kind,
+    name,
+  };
+}
+
+/**
+ * Declare a factory plugin. Use this method in order to type check the dependency graph of your plugin,
+ * @param kind The plugin kind
+ * @param name The name of the plugin
+ * @param factory The factory used to instantiate the plugin
+ */
+export function declareFactoryPlugin<
+  TPluginKind extends PluginKind,
+  Tokens extends Array<InjectionToken<PluginContext>>,
+>(
+  kind: TPluginKind,
+  name: string,
+  factory: InjectableFunction<
+    PluginContext,
+    PluginInterfaces[TPluginKind],
+    Tokens
+  >,
+): FactoryPlugin<TPluginKind, Tokens> {
+  return {
+    factory,
+    kind,
+    name,
+  };
+}
+
+/**
+ * Declare a value plugin. Use this method for simple plugins where you don't need values to be injected.
+ * @param kind The plugin kind
+ * @param name The name of the plugin
+ * @param value The plugin
+ */
+export function declareValuePlugin<TPluginKind extends PluginKind>(
+  kind: TPluginKind,
+  name: string,
+  value: PluginInterfaces[TPluginKind],
+): ValuePlugin<TPluginKind> {
+  return {
+    value,
+    kind,
+    name,
+  };
+}
+
+/**
+ * Lookup type for plugin interfaces by kind.
+ */
+export interface PluginInterfaces {
+  [PluginKind.Reporter]: Reporter;
+  [PluginKind.TestRunner]: TestRunner;
+  [PluginKind.Checker]: Checker;
+  [PluginKind.Ignore]: Ignorer;
+}
+
+/**
+ * Lookup type for plugins by kind.
+ */
+export type Plugins = {
+  [TPluginKind in keyof PluginInterfaces]: Plugin<TPluginKind>;
+};

package/src/plugin/scope.ts

@@ -0,0 +1,6 @@
+export enum Scope {
+  Transient = 'transient',
+  Singleton = 'singleton',
+}
+
+// Keep in sync with import { Scope } from '@typed-inject';

package/src/plugin/tokens.ts

@@ -0,0 +1,35 @@
+/**
+ * Define a string literal.
+ * @param value Token literal
+ */
+function stringLiteral<T extends string>(value: T): T {
+  return value;
+}
+
+const target: import('typed-inject').TargetToken = '$target';
+const injector: import('typed-inject').InjectorToken = '$injector';
+
+/**
+ * Common tokens used for dependency injection (see typed-inject readme for more information)
+ */
+export const commonTokens = Object.freeze({
+  getLogger: stringLiteral('getLogger'),
+  injector,
+  logger: stringLiteral('logger'),
+  options: stringLiteral('options'),
+  fileDescriptions: stringLiteral('fileDescriptions'),
+  target,
+});
+
+/**
+ * Helper method to create string literal tuple type.
+ * @example
+ * ```ts
+ * const inject = tokens('foo', 'bar');
+ * const inject2: ['foo', 'bar'] = ['foo', 'bar'];
+ * ```
+ * @param tokens The tokens as args
+ */
+export function tokens<TS extends string[]>(...tokensList: TS): TS {
+  return tokensList;
+}

package/src/report/dry-run-completed-event.ts

@@ -0,0 +1,22 @@
+import {
+  CompleteDryRunResult,
+  TestRunnerCapabilities,
+} from '../test-runner/index.js';
+
+export interface DryRunCompletedEvent {
+  result: CompleteDryRunResult;
+  timing: RunTiming;
+  capabilities: TestRunnerCapabilities;
+}
+
+export interface RunTiming {
+  /**
+   * The time that the test runner was actually executing tests in milliseconds.
+   */
+  net: number;
+  /**
+   * the time that was spend not executing tests in milliseconds.
+   * So the time it took to start the test runner and to report the result.
+   */
+  overhead: number;
+}

package/src/report/index.ts

@@ -0,0 +1,6 @@
+export type { Reporter } from './reporter.js';
+export type { MutationTestingPlanReadyEvent } from './mutation-testing-plan-ready-event.js';
+export type {
+  DryRunCompletedEvent,
+  RunTiming,
+} from './dry-run-completed-event.js';

package/src/report/mutation-testing-plan-ready-event.ts

@@ -0,0 +1,5 @@
+import { MutantTestPlan } from '../core/index.js';
+
+export interface MutationTestingPlanReadyEvent {
+  mutantPlans: readonly MutantTestPlan[];
+}