Strange: `uri` not a `URI`

[amomchilov]

Contrary to its name, Rubydex::Declaration#uri returns a String. Real users need to use URI.parse(x.uri).path to get what they really wanted, which was the path.

I think we can both improve the ergonomics, and the naming (for least astonishment).

Proposal:

- #: -> String
+ #: -> URI
  def uri; end

+ #: -> Pathname
+ def pathname; end # Perhaps just `path`, it'll be very commonly used

+ #: -> String
+ def uri_string # Returns the raw URI as a string, like `#uri` does today.

[amomchilov]

Decision from our project sync: punt for now. Wait to see more usages, and use that to inform what would be most useful for real-world code.

[Morriar]

We already have Location#to_file_path.

I looked into making Location#uri an actual URI::Generic, while it works it brings 2 pain points:

1. We have to build URI objects for every location and this isn't free.
2. Second, all the other APIs need to use URI as well, which means the user can't just do graph.index_file("foo.rb"), they have to wrap the path in a URI.
   We could make the index_file and friends take a (URI | String) but I'd suggest holding of on that until we have a bit more clients.

[vinistock]

This is related to #313. I do think we need to always use URI objects for both inputs and outputs.

While it requires consumers to parse and produce objects, it also prevents common URI related mistakes by surfacing URI parsing errors on the consumer side.

For example, it's easy to do something like this

uri = "file://#{file_path}"
graph.any_operation(uri)

and not realize that produces invalid URIs on Windows, which can end up having surprising behaviour.