AegisMut

AegisMut is an Angular-first mutation testing engine prototype designed around correctness for large TypeScript, Jest, and Vitest projects.

It combines a Rust control plane with TypeScript runner adapters:

• Rust parser, instrumentation, scheduling, cache keys, IPC types, CLI, and reports
• TypeScript runtime and real Jest/Vitest adapter integrations
• thunk-based mutant switching with strict one-mutant fallback
• dry-run mutation coverage collection
• branch-hit ambiguity guards
• Portable single-file HTML report and Stryker-compatible JSON report output
• Angular workspace, TestBed, template, and Nx metadata discovery

Repository Layout

crates/      Rust crates for CLI, core models, parser, instrumentation, scheduler, cache, report, and IPC
packages/    TypeScript runtime, shared runner contract, Jest/Vitest adapters, Angular adapter
fixtures/    Real Jest/Vitest and Angular-oriented fixtures
docs/        Architecture, correctness model, runner contract, cache, and operator documentation
tests/       Integration tests for fixture mutation runs

Quick Start

Install the CLI from npm:

npm install -g aegismut
aegis run --runner jest --config aegis.config.json

The npm package currently builds the Rust CLI during install, so Rust/Cargo must be available on the machine. Install Rust with rustup if npm install -g aegismut reports that Cargo is missing.

Publish from this repository:

npm login
npm run publish:npm

Packages are published in dependency order: @aegismut/runtime, @aegismut/shared-runner, runner adapters, Angular adapter, then the aegismut CLI package.

Local development:

pnpm install
npm run build
pnpm test
cargo test --workspace

Run the fixture mutation flows:

cargo run -p aegis-cli -- run --runner jest --config fixtures/angular-jest/aegis.config.json
cargo run -p aegis-cli -- run --runner vitest --config fixtures/angular-vitest/aegis.config.json

Reports are emitted under each fixture's reports/ directory:

• index.html: self-contained report viewer with embedded data
• aegis-report.json: native AegisMut JSON
• stryker-report.json: Stryker-compatible JSON

Correctness Model

AegisMut treats strict first-order mutation execution as the source of truth: same real runner, same user config, one mutant active at a time, and equivalent timeout/pass/fail/error interpretation.

Fast paths are permitted only when they are semantics-preserving, verified, or guarded by fallback. Variant results with more than one mutated branch taken are considered ambiguous and must be split/replayed or routed to strict fallback.

Status

This repository contains the initial implementation and vertical slice. It is intentionally conservative: performance-oriented worker and virtualization skeletons exist, but correctness remains the baseline.

Known limitations are documented in:

• Architecture
• Correctness Model
• Runner Contract
• Mutation Operators
• Cache Invalidation

License

MIT