# muter-mutation-testing/muter architecture

> Architecture diagram of the GitHub repository muter-mutation-testing/muter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/muter-mutation-testing/muter
- Repository: https://github.com/muter-mutation-testing/muter

## Overview

##### Main Components
- CLI Interface & Entry Point: The “Sources/muter” directory (main.swift) serves as the primary entry point that receives user commands. This layer parses arguments (like “init”, “run”, “mutate-without-running”, etc.) and directs control.
- Core Mutation Engine (muterCore): This is a collection of modules that implement the logic of mutation testing. It is further subdivided into several key packages:
- CLICommands: Contains subcommands such as “Init”, “Muter”, “RunCommand”, etc.
- BuildSystems: Includes support for different build environments, for example under BuildSystems/Swift and BuildSystems/Xcode.
- Configuration: Reads and interprets the configuration file (muter.conf.yml) and manages runtime settings.
- DependencyInjection: Provides flexibility by managing dependencies (see “Dependency.swift” and “World.swift”).
- MutationOperators: Implements specific mutation operators (e.g., ROROperator, SwapTernaryOperator).
- MutationSchemata: Houses logic to build a “mutant test plan” (see MuterTestPlan.swift) that maps mutation points.
- MutationSteps: Contains ordered steps (e.g., CopyProjectToTempDirectory, DiscoverMutationPoints, BuildForTesting) that mutate, rebuild, and test the code.
- MutationTesting: Implements strategies for running tests in a mutated environment and monitoring outcomes.
- Rewriters: Contains source code transformation logic (for instance, AddImportRewriter, DisableLintersRewriter, MuterRewriter).
- Shell & SourceCodeOperations: Manages interactions with the file system and external processes.
- TestReporting: Aggregates and formats mutation testing outcomes. It supports various report formats (plain text, JSON, HTML, and even Xcode’s format).
- Visitors: Uses the Swift AST to navigate source code and apply transformations.
- Extensions: Helpful utility functions used across the modules.
- Versioning: Contains version control information.
- External Integrations and Examples:
- The Repositories folder contains several sample applications (e.g., BonMot, ExampleApp, and FFCParserCombinator) that are used to demonstrate how Muter works with real-world projects.
- AcceptanceTests and RegressionTests directories represent automated test suites to validate that Muter works as expected.
- CI and other scripts (in the “Scripts” directory) handle automated version bumping, test coverage extraction, and integration steps.

##### Relationships and Data Flows
- The CLI layer receives user input (commands and flags) and passes this to the CLICommands module.
- Based on user commands, the configuration module reads the “muter.conf.yml” file to determine how to interact with the build systems.
- The BuildSystems module then executes the proper external test command, either calling xcodebuild, swift, or other tools.
- The MutationOperators along with the Rewriters analyze the source code (using the Visitors and Extensions) to inject mutations according to defined schemata.
- The MutationSteps module coordinates sequential tasks: discovering mutation points, modifying a temporary copy of the project, building the project, and then running tests.
- As tests run under different mutation settings, the MutationTesting module records which mutants are “killed” (detected by the tests) versus those that survive.
- Finally, the TestReporting module takes these outcomes and formats them for display on the CLI, within CI logs, or even for Xcode integration.
- DependencyInjection and Shell modules serve as infrastructure supporting various operations and allow for testability and easier extension.

##### Architectural Patterns and Principles
- Layered Architecture: The project separates concerns—input/command handling, mutation logic and transformation (core engine), external build/test interaction, and reporting.
- Modularity: Each logical function (such as mutation operators, rewriters or build system adaptations) lives in its own module, making the system extensible and maintainable.
- Dependency Injection: This design pattern is used to decouple concrete dependencies from the core logic, making the modules easier to test.
- Test-Driven Design: The abundance of unit tests (in the Tests folder) and various test suites reinforces that each component is designed to be independently tested.

##### Relevant Technologies, Frameworks, and Libraries
- Swift (Swift 5.9 is explicitly supported, as indicated by the README)
- Xcode and Swift Package Manager: The build system support caters to both environments.
- Command-line tools and scripting (e.g., bash scripts in the Scripts directory)
- The integration with CI pipelines as mentioned in the README and acceptance/regression test setups.

##### Capturing Essential Architectural Elements
- Don’t shy away from breaking down modules into as many components as needed. The goal is to show all the important layers—from configuration and mutation planning through execution and reporting.
- External integrations (like CI and Xcode) and include sample repositories for testing as separate, but connected, components illustrating how Muter is used in different contexts.

- Frontend components (CLI/Xcode integration)
- Core engine internals (divided by their logical responsibilities)
- External interactions (build systems, CI scripts, test reporting)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Interface
    CLI["CLI Interface / Entry Point"]:::cli

    %% Core Mutation Engine
    subgraph "Core Mutation Engine"
        CLICommands["CLICommands Module"]:::core
        Config["Configuration Module"]:::core
        Dependency["Dependency Injection"]:::core

        subgraph "Mutation Transformation"
            MutOperators["Mutation Operators"]:::core
            Rewriter["Rewriters"]:::core
            Visitor["Visitors"]:::core
            Extension["Extensions"]:::core
        end

        subgraph "Mutation Planning & Execution"
            MutSchemata["Mutation Schemata"]:::core
            MutSteps["Mutation Steps"]:::core
        end

        subgraph "Build Systems Integration"
            BuildSystems["Build Systems Integration"]:::core
            SwiftBuild["Swift Build Support"]:::core
            XcodeBuild["Xcode Build Support"]:::core
        end

        subgraph "Test Runner & Reporter"
            MutTesting["Mutation Testing"]:::reporting
            TestReport["Test Reporting"]:::reporting
            ShellOps["Shell Operations"]:::reporting
            SourceOps["Source Code Operations"]:::reporting
        end

        Versioning["Versioning Information"]:::core
    end

    %% External Integrations & Examples
    subgraph "External Integrations & Examples"
        ExampleRepos["Example Repositories"]:::external
        Acceptance["Acceptance Tests"]:::external
        Regression["Regression Tests"]:::external
        CIScripts["CI and Scripts"]:::external
    end

    %% Connections between components
    CLI -->|"parseCommands"| CLICommands
    CLI -->|"readConfig"| Config
    CLICommands -->|"initConfig"| Config
    Config -->|"setupDependencies"| Dependency
    Config -->|"configureBuild"| BuildSystems

    BuildSystems -->|"selectEnvironment"| SwiftBuild
    BuildSystems -->|"selectEnvironment"| XcodeBuild

    MutOperators -->|"applyMutations"| MutSchemata
    Rewriter -->|"rewriteSource"| MutSchemata
    Visitor -->|"analyzeAST"| MutSchemata
    Extension -->|"utilFunctions"| MutSchemata

    MutSchemata -->|"planMutations"| MutSteps
    MutSteps -->|"triggerTests"| MutTesting
    BuildSystems -->|"executeTests"| MutTesting

    MutTesting -->|"collectResults"| TestReport
    ShellOps -->|"handleFiles"| TestReport
    SourceOps -->|"processSource"| TestReport

    TestReport -->|"outputResults"| CLI

    %% External integrations flowing into core process
    ExampleRepos -->|"validateUsage"| MutTesting
    Acceptance -->|"automatedTests"| MutTesting
    Regression -->|"automatedTests"| MutTesting
    CIScripts -->|"ciIntegration"| TestReport

    Versioning -.->|"versionInfo"| CLI

    %% Click Events
    click CLI "https://github.com/muter-mutation-testing/muter/blob/master/Sources/muter/main.swift"
    click CLICommands "https://github.com/muter-mutation-testing/muter/tree/master/Sources/muterCore/CLICommands"
    click Config "https://github.com/muter-mutation-testing/muter/tree/master/Sources/muterCore/Configuration"
    click Dependency "https://github.com/muter-mutation-testing/muter/tree/master/Sources/muterCore/DependencyInjection"
    click MutOperators "https://github.com/muter-mutation-testing/muter/tree/master/Sources/muterCore/MutationOperators"
    click Rewriter "https://github.com/muter-mutation-testing/muter/tree/master/Sources/muterCore/Rewriters"
    click Visitor "https://github.com/muter-mutation-testing/muter/tree/master/Sources/muterCore/Visitors"
    click Extension "https://github.com/muter-mutation-testing/muter/tree/master/Sources/muterCore/Extensions"
    click MutSchemata "https://github.com/muter-mutation-testing/muter/tree/master/Sources/muterCore/MutationSchemata"
    click MutSteps "https://github.com/muter-mutation-testing/muter/tree/master/Sources/muterCore/MutationSteps"
    click SwiftBuild "https://github.com/muter-mutation-testing/muter/tree/master/Sources/muterCore/BuildSystems/Swift"
    click XcodeBuild "https://github.com/muter-mutation-testing/muter/tree/master/Sources/muterCore/BuildSystems/Xcode"
    click BuildSystems "https://github.com/muter-mutation-testing/muter/tree/master/Sources/muterCore/BuildSystems"
    click MutTesting "https://github.com/muter-mutation-testing/muter/tree/master/Sources/muterCore/MutationTesting"
    click TestReport "https://github.com/muter-mutation-testing/muter/tree/master/Sources/muterCore/TestReporting"
    click ShellOps "https://github.com/muter-mutation-testing/muter/tree/master/Sources/muterCore/Shell"
    click SourceOps "https://github.com/muter-mutation-testing/muter/tree/master/Sources/muterCore/SourceCodeOperations"
    click Versioning "https://github.com/muter-mutation-testing/muter/blob/master/Sources/muterCore/version.swift"
    click ExampleRepos "https://github.com/muter-mutation-testing/muter/tree/master/Repositories"
    click Acceptance "https://github.com/muter-mutation-testing/muter/tree/master/AcceptanceTests"
    click Regression "https://github.com/muter-mutation-testing/muter/tree/master/RegressionTests"
    click CIScripts "https://github.com/muter-mutation-testing/muter/tree/master/Scripts"

    %% Styles
    classDef cli fill:#A2D5AB,stroke:#333,stroke-width:2px;
    classDef core fill:#A3C1DA,stroke:#333,stroke-width:2px;
    classDef reporting fill:#F5B0CB,stroke:#333,stroke-width:2px;
    classDef external fill:#FFD8A9,stroke:#333,stroke-width:2px;
```
