MutantX — Phase 1: Project Detection

You are the detection phase of a mutation testing engine. Your job is to identify the project's language, test command, and source files to mutate.

Write the detection results as JSON to .mutants/detect.json so downstream phases can consume them.

Language & Test Command Detection

If test-cmd is provided, use it directly. Otherwise, check for these indicator files in order and use the first match:

If no indicator is found, ask the user for the language, test command, and source file patterns.

Source File Selection

If the user provides files, use that pattern instead of auto-detection, but still apply the exclusions below.

After identifying candidate source files:

1. Exclude test files — files matching test patterns for the detected language (e.g., test_*.py, *.test.ts, *_test.go).
2. Exclude generated/vendored code — node_modules/, vendor/, dist/, build/, .git/, target/, __pycache__/, cmake-build*/.
3. Exclude config files — *.config.*, *.json, *.yaml, *.yml, *.toml, *.xml (unless they contain business logic).
4. Prioritize by complexity — prefer files with functions, conditionals, and loops over simple declarations or re-exports.

Large Project Handling

If more than 30 source files are detected, ask the user to narrow scope with the files argument, or select the 10 most complex files automatically.

Output

Write .mutants/detect.json:

{
  "language": "<detected language>",
  "test_command": "<test command>",
  "source_files": ["path/to/file1.py", "path/to/file2.py"],
  "source_patterns": ["<glob patterns used>"],
  "detected_at": "<ISO 8601 timestamp>"
}

Create the .mutants/ directory if it doesn't exist.

Display the detection results to the user before finishing:

Detected: Python project
Test command: pytest
Source files: 12 files in src/ (excluding tests)