this is the beginning of a refactor with the intention to address #133. i'm using the time to do housekeeping. creating a draft PR here so we can discuss the changes.

remove "property" module

before Graph was a struct, it was a trait object, with the idea that we might have different graph representations. we dropped that idea but still Vertex and Edge implementations were living in a separate module called "property" (for Graphs with properties). this PR moves Vertex and Edge into the module with the rest of the graph stuff, and that module has been renamed from road_network to network for simplicity.

pass EdgeId/VertexId/Direction by reference in Graph methods

we are passing these newtypes by value which i believe triggers a clone. i previously thought the compiler would recognize a built-in under-the-hood but i have heard otherwise on recent searches. this way the signatures match the general idiom of passing immutable values into functions in rust.

for example, a before-and-after:

// previous
let result = graph.dst_vertex_id(VertexId(0))?;

// new
let result = graph.dst_vertex_id(&VertexId(0))?;

Graph in/out/incident edges methods no longer fail

the in_edges, out_edges, and incident_edges methods previously failed if there wasn't an entry for their argument vertex in the forward or reverse adjacency lists, based on the assumption that we are always working with a strongly-connected graph. while that is sensible, it's not robust, for example if people are working with modified graphs or crowd-sourced datasets. if it truly should produce an error, that can be decided at the calling scope.

use eprintln! macro instead of println! macro for kdam::Bar

kdam writes the progress bar to stderr, not stdout.

about errors

i wanted to make things a little more consistent and to reduce fracturing, and so, for a lot of the system, i simplified things to Build, Runtime, and Internal errors, both single-String-parameter enum variants:

enum MyError {
  #[error("failure building my model due to {0}")]
  BuildFailure(String),
  #[error("failure while running my model due to {0}"]
  RuntimeFailure(String),
  #[error("{0}")]
  InternalError(String)
}

so:

• if we had a bunch of different variants that seemed to fit into these categories, i removed those variants
• other modules seemed to benefit from being more specific, and that felt appropriate lower-down in the module stack, like the road network operations
• i revised the composition between error types so it's cleaner
• more information is communicated between nested errors where appropriate (see SearchError)
• removed transparent error variants (no transparent errors should bubble to top of app #183)
• leveraged the macro-generated "From" implementations for easy error type propagation
  • for example, in EdgeTraversal, a bunch of errors come from different models, but the compiler calls the SearchError::from method when ? is called on those results

with these changes, CompassAppErrors should now have the right amount of context for most situations.

Closes #133.
Closes #183.