feat: better mutant descriptions

[nhaajt]

Overview

• Update mutator names, descriptions, and docs for better consistency
• Add the ability to define better descriptions specific to each mutation
• Add specific mutation descriptions for built-in mutators

Specific mutation description

Specific mutation description can be defined per mutator that extends TokenMutator by overriding the description method, which provides the original and mutated string representation of the targeted token and the mutation location:

object CharClassNegation extends TokenMutator {
  override val name = "Character class negation"
  override val levels: Seq[Int] = Seq(1)
  override def description(original: String, mutated: String, location: Location): String =
    s"${location.pretty} Negate the character class `$original` to `$mutated`"

  override def mutate(token: RegexTree): Seq[Mutant] = ...
}

With the above definition, the new descriptions for a CharClassNegation would be:

// Original regex
"[ab0-9[A-Z][cd]]"
// Mutants
"[^ab0-9[A-Z][cd]]"
"[ab0-9[^A-Z][cd]]"
"[ab0-9[A-Z][^cd]]"

// Before (same for all mutants)
"Negate character class"
// After
"[0:0, 0:1) Negate the character class `[ab0-9[A-Z][cd]]` to `[^ab0-9[A-Z][cd]]`"
"[0:6, 0:7) Negate the character class `[A-Z]` to `[^A-Z]`"
"[0:11, 0:12) Negate the character class `[cd]` to `[^cd]`"

If more mutation information is desired, a mutation description can also be directly specified during mutation as an argument for the toMutantOf, toMutantBeforeChildrenOf, or toMutantAfterChildrenOf extension methods:

object CharClassChildRemoval extends TokenMutator {
  override val name: String = "Character class child removal"
  override val levels: Seq[Int] = Seq(2, 3)

  override def mutate(token: RegexTree): Seq[Mutant] = {
    def _mutate(token: Node): Seq[Mutant] = token.children map (child =>
      token
        .buildWhile(_ ne child)
        .toMutantOf(
          child,
          description =
            s"${child.location.pretty} Remove the child `${child.build}` from the character class `${token.build}`"
        )
    )

    token match {
      case cc: CharacterClass if cc.children.length > 1      => _mutate(cc)
      case cc: CharacterClassNaked if cc.children.length > 1 => _mutate(cc)
      case _                                                 => Nil
    }
  }
}

New mutant descriptions for a CharClassChildRemoval are shown below:

// Original regex
"[ab0-9[A-Z][cd]]"
// Mutants
"[b0-9[A-Z][cd]]"
"[a0-9[A-Z][cd]]"
"[ab[A-Z][cd]]"
"[ab0-9[cd]]"
"[ab0-9[A-Z]]"
"[ab0-9[A-Z][d]]"
"[ab0-9[A-Z][c]]"

// Before (same for all mutants)
"Remove a child from a character class"
// After
"[0:1, 0:2) Remove the child `a` from the character class `[ab0-9[A-Z][cd]]`"
"[0:2, 0:3) Remove the child `b` from the character class `[ab0-9[A-Z][cd]]`"
"[0:3, 0:6) Remove the child `0-9` from the character class `[ab0-9[A-Z][cd]]`"
"[0:6, 0:11) Remove the child `[A-Z]` from the character class `[ab0-9[A-Z][cd]]`"
"[0:11, 0:15) Remove the child `[cd]` from the character class `[ab0-9[A-Z][cd]]`"
"[0:12, 0:13) Remove the child `c` from the character class `[cd]`"
"[0:13, 0:14) Remove the child `d` from the character class `[cd]`"

Breaking changes

• TokenMutator.description removed in favor of using TokenMutator.description(original: String, mutated: String, location: Location): String to define and generate a more detailed description for each mutant instead of the mutator.

[hugo-vrijswijk]

Nice! I like the implementation. It's pretty clean and makes sense. Some minor comments.

[hugo-vrijswijk]

Rather than pretty, how about show? This is also in line with the cats typeclass

Suggested change

	val pretty: String = s"[${start.pretty}, ${end.pretty})"
	def show: String = s"[${start.show}, ${end.show})"

[nhaajt]

Updated 🧐 Good to know.

[hugo-vrijswijk]

LGTM feel free to (squash) merge