Extract a generic depth-first graph traversal algorithm

[tslil-topos]

What

catlog contains a toposort function for graphs which uses mutli-start DFS (twice), this DFS was previously inlined. This change extracts the DFS procedure for FinGraph into a hopefully more re-usable method depth_first_traversal for the library.

Closes #719

Notes

• introduces an enum TraversalDirection because Graph is the category-theoretic graph (we need to know whether we're going into or out of a node)
• adds some test cases for depth_first_traversal
• there is potentially a performance/memory difference between the old code and the new code because we now create new Vecs for the stack on every invocation of depth_first_traversal. It's difficult for me to reason about this without understanding the compiler optimisation more
• honestly i'm not sure that this refactor brings immediate value, in fact looking around at the algorithms it's quite possible that toposort could have been re-written in terms of spec_order

[epatters]

Thanks tslil, this is nice! A few comments below.

honestly i'm not sure that this refactor brings immediate value, in fact looking around at the algorithms it's quite possible that toposort could have been re-written in terms of spec_order

I'm inclined to agree that this is a preemptive refactor, which can run the risk of being premature, but I've got a feeling that one way or another we're going end up writing more graph algorithms that require a DFS. So hopefully it will pay off.

[epatters]

Not a graph algorithms person myself, but I feel like the more common/expected behavior of a DFS algorithm is that when it encounters a cycle, including as a special case a self-loop, it should detect it and avoid looping infinitely and otherwise proceed without error, instead of returning an Err as here.

(I suspect this is just leftover logic from the toposort alg from which it was extracted.)

[epatters]

It's always ungainly in Rust, which has only positional arguments, to have so arguments to a function or method. In this case, what I'd probably do is split up the internal state persisted across invocations and the arguments for a single run, something like:

struct DFS<V> {
    discovered: HashSet<V>,
    traversal_direction: TraversalDirection
}

impl<V> DFS<V> {
    pub fn traverse(graph, start_vertex, ...)
}

If you're not familiar with it, you might also check out the builder pattern, which is an idiomatic way to work around Rust's lack of keyword arguments.