Major refactoring of the EquivalencyValidator

[dennisdoomen]

After a master-class on maintainable code I recently gave, I realized there's still a lot to improve on the equivalency validation code.

• Renamed IEquivalencyValidator to a more role-based named
• Encapsulated isComplexTypeMap into ComplexTypeMap
• Reduce usage of AssertionScope.Current in EquivalencyValidator
• Attach CyclicReferenceDetector to the EquivalencyValidationContext instead of the current AssertionScope and expose IsCycleReference through IEquivalencyValidationContext
• Removed CanHandle from IEquivalencyStep
• Changed the return value of IEquivalencyStep.Handle into an enum with values ContinueWithNext and AssertionCompleted
• Split-off the subject and expectation from IEquivalencyValidationContext into Comparands to emphasize what we're comparing
• Renamed EquivalencyStepCollection to EquivalencyPlan as well as the corresponding AssertionOptions property
• Added the typed base-class EquivalencyStep<T> for convenience
• Updated the extensibility documentation as well as the upgrade section

Fixes #1534

[dennisdoomen]

@jnyrup thoughts on this (before I go to far)?

[jnyrup]

I'm not sure I see the use cases or need for specifying Nested and Recursively 🤔
Nested is a part of how we define equivalency.
Recursively is an implementation detail of how we verify equivalency.

[dennisdoomen]

During several of my masterclasses, the students mentioned that it was not obvious that this method would be called recursively. By adding this to the name, it would be enough of a hint to think about the consequences.

[jnyrup]

Playing the devil's advocate:
Why do you need to know it's recursive?
If I call a Sort function on sequence I don't know whether it's recursively or iteratively implemented, only that upon return I have a sorted sequence.

brain storming some names:

• ValidateEquivalency
• Validate (since the Equivalency part is already part of the interface name)

[dennisdoomen]

You need to make sure it's re-entrant. But I fail to come up with a good example of that right now..

[dennisdoomen]

I meant with the planned improvements in the bullet list ;-)

[jnyrup]

A rework of IEquivalencyStep sounds great!

• I've never fully understood (or maybe I just forgot) the Boolean that Handle returns.
• Combining CanHandle and Handle to a single TryHandle could also give a small performance boost, as we currently throw away the knowledge we obtain in CanHandle.
• If we reworking IEquivalencyStep anyways, I'm fine with renaming it.
  • Just note that renames in our extensibility types will make migration for our users a bit harder.

For the remaining I'm not sure what the consequences are, but I have no immediate objects.

[dennisdoomen]

@jnyrup I tried to split the changes into atomic commits, but almost everything affected everything else, at some point I gave up. But if it would help you, I could split them up in commits that won't compile individually. Just let me know.