Custom Mutators.md

Custom Mutators

TypeStat allows using custom mutators instead of the built-in mutators, similar to custom ESLint rules. Built-in mutators will be disabled if you provide any custom ones.

Usage

Use the -m/--mutators CLI flag and/or mutators configuration setting to add require-style paths of mutators to add.

{
	"mutators": ["my-mutator-module"]
}

These will be run in order of inclusion, starting with mutators specified on the CLI.

Development

In order to create a custom mutator included by an added path, that added path must resolve from Node's require to a file that exports a .mutator function.

That mutator will receive a single request parameter of type FileMutationsRequest. It should return an array of Automutate Mutation objects.

For example, if you run typestat --add ./src/mutators/myMutator, there should exist a ./src/mutators/myMutator.js file (or ./src/mutators/myMutator/index.js):

import { Mutation } from "automutate";
import { FileMutationsRequest } from "typestat";

export const mutator = (request: FileMutationsRequest): Mutation[] => {
	// TODO: Implement!
	return [];
};

Mutators must be compiled to JavaScript to be run.

For example, this mutator will add a /* foo */ mutation at the beginning of each file it visits, if one doesn't yet exist in the file:

const prefix = "/* foo */ ";

module.exports.fileMutator = (request) => {
	return request.sourceFile.getFullText().startsWith(prefix)
		? []
		: [
				{
					insertion: prefix,
					range: {
						begin: 0,
					},
					type: "text-insert",
				},
			];
};