# stryker-mutator/stryker-js architecture

> Architecture diagram of the GitHub repository stryker-mutator/stryker-js, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stryker-mutator/stryker-js
- Repository: https://github.com/stryker-mutator/stryker-js

## Overview

##### Project type and purpose
- This is StrykerJS: an open-source, monorepo-based mutation-testing framework for JavaScript and TypeScript.
- It bundles a pluggable core engine, instrumentation and mutator libraries, adapters (“runners”) for various test frameworks, CLI tools, and helper utilities.

##### High-level architecture
At the highest level, Stryker executes as a CLI that:
a. Loads your configuration (via config reader).
b. Instantiates a dependency-injection container.
c. Loads plugins (instrumenters, mutators, test-runner adapters, reporters).
d. Orchestrates a pipeline of executors (prepare, instrument, dry-run, mutation test).
e. Spawns sandboxed child processes to run tests.
f. Aggregates results and emits reports.

##### Main components
A. CLI entrypoint (“stryker” / `packages/core/bin/stryker.js`)
– Reads arguments, locates a config file (default or `stryker.conf.js`)
– Delegates to the Core Orchestrator
B. Config Reader (`packages/core/src/config`)
– Merges defaults, CLI overrides, and config file
C. DI Container & Plugin Loader (`packages/core/src/di`, `packages/api/src/plugin`)
– Registers tokens and loads plugins by kind (instrumenter, runner, reporter, checker)
D. Core Orchestrator (`packages/core/src/process`)
– Sequential executors:
1. PrepareExecutor: validation, input-file reading
2. InstrumenterExecutor: calls Instrumenter
3. DryRunExecutor: runs tests once without mutants
4. MutationTestExecutor: loops over mutants, runs tests per mutant
E. Instrumenter (`packages/instrumenter`)
– Parses source files, applies mutator plugins, generates instrumented code
F. Sandbox (`packages/core/src/sandbox`)
– Creates child-process or worker sandboxes for isolation
– Preprocesses files (e.g., ts-config rewriting)
G. Test-Runner Adapters (`packages/*-runner`)
– Jasmine, Mocha, Jest, Karma, Tap, Cucumber, Vitest, etc.
– Each plugin wraps the external framework, instruments it for mutation analysis, reports back test results
H. Checker (`packages/typescript-checker`)
– Optionally type-checks sources to prune impossible mutations
I. Reporter Plugins (`packages/core/src/reporters`, plus external dashboard CI plugins)
– Console reporters (clear-text, progress, dots)
– HTML, JSON, dashboard back-ends
J. Utilities (`packages/util`, `packages/api`, logging)
– Shared logging infrastructure (`packages/core/src/logging`, `packages/api/src/logging`)
– Common helpers (deep-merge, child-process handling, schema validation)

##### Relationships and data flow
1. User invokes CLI → Core Orchestrator
2. Orchestrator asks Config Reader → Combined options
3. DI Container + Plugin Loader → Instantiated plugins: instrumenter, mutators, test runners, reporters, checker
4. PrepareExecutor → reads file system (`packages/core/src/fs`)
5. InstrumenterExecutor → Instrumenter produces instrumented code artifacts
6. DryRunExecutor → Sandbox + Test-Runner → “baseline” test results
7. MutationTestExecutor → For each mutant:
- Mutant placement via instrumenter
- Tests run in Sandbox + Test-Runner
- Test-Runner reports pass/fail back
8. Reporter plugins subscribe to events (dry-run completed, mutation test ready) and render output

##### Architectural patterns and design principles
- Modular Plugin Architecture: everything is a plugin (instrumenters, runners, reporters) loaded via DI
- Executor Pipeline: linear sequence of stages, each stage injection-based
- Sandbox Isolation: child processes to reliably reset environment per mutant/test run
- Monorepo with Strict Boundaries: each `packages/*` has its own tests, config, and published artifact
- Separation of Concerns:
– Core orchestrator concerns vs. test-framework adapters vs. code mutation logic

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Engine Components
    CLI["CLI Entrypoint\n(stryker)"]:::core
    click CLI "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/bin/stryker.js"
    click CLI "https://github.com/stryker-mutator/stryker-js/tree/master/packages/core/bin/stryker"
    Config["Config Reader"]:::core
    click Config "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/config/config-reader.ts"
    click Config "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/config/index.ts"
    DI["DI Container + Plugin Loader"]:::core
    click DI "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/di/index.ts"
    click DI "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/di/plugin-loader.ts"
    click DI "https://github.com/stryker-mutator/stryker-js/tree/master/packages/api/src/plugin"
    StrykerCLI["Stryker CLI Adapter"]:::core
    click StrykerCLI "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/stryker-cli.ts"
    Orchestrator["Core Orchestrator"]:::core
    click Orchestrator "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/stryker.ts"
    click Orchestrator "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/process/index.ts"

    %% Executor Pipeline
    subgraph "Executor Pipeline"
      direction TB
      Prepare["1. PrepareExecutor"]:::core
      click Prepare "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/process/1-prepare-executor.ts"
      MutInstrExec["2. InstrumenterExecutor"]:::core
      click MutInstrExec "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/process/2-mutant-instrumenter-executor.ts"
      DryRunExec["3. DryRunExecutor"]:::core
      click DryRunExec "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/process/3-dry-run-executor.ts"
      MutationExec["4. MutationTestExecutor"]:::core
      click MutationExec "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/process/4-mutation-test-executor.ts"
    end

    %% Instrumenter
    Instrumenter["Instrumenter"]:::instr
    click Instrumenter "https://github.com/stryker-mutator/stryker-js/blob/master/packages/instrumenter/src/instrumenter.ts"
    click Instrumenter "https://github.com/stryker-mutator/stryker-js/blob/master/packages/instrumenter/src/create-instrumenter.ts"
    click Instrumenter "https://github.com/stryker-mutator/stryker-js/tree/master/packages/instrumenter/src/mutators"
    click Instrumenter "https://github.com/stryker-mutator/stryker-js/tree/master/packages/instrumenter/src/parsers"
    click Instrumenter "https://github.com/stryker-mutator/stryker-js/tree/master/packages/instrumenter/src/transformers"

    %% Sandbox
    Sandbox["Sandbox"]:::core
    click Sandbox "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/sandbox/index.ts"
    click Sandbox "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/sandbox/sandbox.ts"
    click Sandbox "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/sandbox/create-preprocessor.ts"
    click Sandbox "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/sandbox/ts-config-preprocessor.ts"

    %% Test-Runner Adapters
    TestRunners["Test-Runner Adapters"]:::runner
    click TestRunners "https://github.com/stryker-mutator/stryker-js/tree/master/packages/jasmine-runner/src"
    click TestRunners "https://github.com/stryker-mutator/stryker-js/tree/master/packages/mocha-runner/src"
    click TestRunners "https://github.com/stryker-mutator/stryker-js/tree/master/packages/jest-runner/src"
    click TestRunners "https://github.com/stryker-mutator/stryker-js/tree/master/packages/karma-runner/src"
    click TestRunners "https://github.com/stryker-mutator/stryker-js/tree/master/packages/tap-runner/src"
    click TestRunners "https://github.com/stryker-mutator/stryker-js/tree/master/packages/cucumber-runner/src"
    click TestRunners "https://github.com/stryker-mutator/stryker-js/tree/master/packages/vitest-runner/src"

    %% Checker
    Checker["Checker (TypeScript)"]:::core
    click Checker "https://github.com/stryker-mutator/stryker-js/blob/master/packages/typescript-checker/src/typescript-checker.ts"
    click Checker "https://github.com/stryker-mutator/stryker-js/blob/master/packages/typescript-checker/src/plugin-tokens.ts"

    %% Reporter Plugins
    Reporters["Reporter Plugins"]:::reporter
    click Reporters "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/reporters/index.ts"
    click Reporters "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/reporters/clear-text-reporter.ts"
    click Reporters "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/reporters/html-reporter.ts"
    click Reporters "https://github.com/stryker-mutator/stryker-js/blob/master/packages/core/src/reporters/json-reporter.ts"
    click Reporters "https://github.com/stryker-mutator/stryker-js/tree/master/packages/core/src/reporters/dashboard-reporter"

    %% Utilities & Logging
    Util["Utilities & Logging"]:::util
    click Util "https://github.com/stryker-mutator/stryker-js/tree/master/packages/util/src"
    click Util "https://github.com/stryker-mutator/stryker-js/tree/master/packages/core/src/logging"
    click Util "https://github.com/stryker-mutator/stryker-js/tree/master/packages/api/src/logging"

    %% Data Flow and Relationships
    CLI -->|invokes| Config
    Config -->|provides options| DI
    DI -->|injects| StrykerCLI
    StrykerCLI -->|starts| Orchestrator
    Orchestrator --> Prepare
    Prepare --> MutInstrExec
    MutInstrExec --> DryRunExec
    DryRunExec --> MutationExec

    %% Executors interactions
    MutInstrExec -->|uses| Instrumenter
    DryRunExec -->|spawns| Sandbox
    DryRunExec -->|runs tests| TestRunners
    MutationExec -->|applies mutants via| Instrumenter
    MutationExec -->|spawns| Sandbox
    MutationExec -->|runs tests| TestRunners

    %% Plugin wiring
    DI -->|loads| Instrumenter
    DI -->|loads| TestRunners
    DI -->|loads| Checker
    DI -->|loads| Reporters
    DI -->|uses| Util

    %% Reporting
    DryRunExec -->|events| Reporters
    MutationExec -->|events| Reporters

    %% Class Definitions
    classDef core fill:#D6E4F0,stroke:#3182bd
    classDef instr fill:#FFD8A8,stroke:#dd6b20
    classDef runner fill:#C6F6D5,stroke:#38A169
    classDef reporter fill:#E9D8FD,stroke:#805AD5
    classDef util fill:#E2E8F0,stroke:#4A5568
```
