Distinguish Document path from name and parse URIs robustly

Previously the Document `path` property returned the URI basename, making
it identical to a name and mislabeled. Split them:

- `uri`  -> full document URI (e.g. file:///app/models/user.rb)
- `path` -> file-system path (e.g. /app/models/user.rb)
- `name` -> base file name (e.g. user.rb)

Add `Document::file_path` / `Document::file_name`, which decode the URI via
the `url` crate (already a dependency) so percent-encoding and platform
paths (including Windows drive paths) are handled correctly instead of
naively splitting on '/'. `require_path` now reuses `file_path` instead of
re-parsing the URI. Non-file:// URIs (the synthetic built-in document) fall
back to the raw URI. Clarify that `prop` is the property name read off a
node, and advertise the new `name` property in the schema.

Author: paracycle

rust/rubydex/src/model/document.rs

@@ -84,6 +84,28 @@ impl Document {
         self.diagnostics.push(diagnostic);
     }
 
+    /// The file-system path of this document, decoded from its URI.
+    ///
+    /// Returns `None` when the URI is not a `file://` URL (e.g. the synthetic built-in document) or
+    /// cannot be converted to a path. Uses `Url` so percent-encoding and platform-specific paths
+    /// (including Windows drive paths) are handled correctly.
+    #[must_use]
+    pub fn file_path(&self) -> Option<PathBuf> {
+        let url = Url::parse(&self.uri).ok()?;
+        if url.scheme() != "file" {
+            return None;
+        }
+        url.to_file_path().ok()
+    }
+
+    /// The base file name of this document (the last path segment), decoded from its URI.
+    ///
+    /// Returns `None` when the URI has no file path (see [`Document::file_path`]).
+    #[must_use]
+    pub fn file_name(&self) -> Option<String> {
+        Some(self.file_path()?.file_name()?.to_string_lossy().into_owned())
+    }
+
     /// Computes the require path for this document given load paths.
     ///
     /// Returns `None` if:
@@ -97,12 +119,7 @@ impl Document {
     /// Panics if load path entries exceed u16.
     #[must_use]
     pub fn require_path(&self, load_paths: &[PathBuf]) -> Option<(String, u16)> {
-        let url = Url::parse(&self.uri).ok()?;
-        if url.scheme() != "file" {
-            return None;
-        }
-
-        let file_path = url.to_file_path().ok()?;
+        let file_path = self.file_path()?;
         if file_path.extension().is_none_or(|ext| ext != "rb") {
             return None;
         }

rust/rubydex/src/query/cypher/schema.rs

@@ -255,13 +255,13 @@ pub fn node_name(graph: &Graph, node: NodeRef) -> String {
             .and_then(|decl_id| graph.declarations().get(decl_id))
             .map_or_else(String::new, |declaration| declaration.name().to_string()),
         NodeRef::Document(id) => graph.documents().get(&id).map_or_else(String::new, |document| {
-            let uri = document.uri();
-            uri.rsplit('/').next().unwrap_or(uri).to_string()
+            document.file_name().unwrap_or_else(|| document.uri().to_string())
         }),
     }
 }
 
-/// Resolves a node property to a value. Unknown properties yield `NULL`.
+/// Resolves a node property to a value, where `prop` is the property name read off the node (the
+/// `x` in `RETURN n.x` / `WHERE n.x = ...`). Unknown properties yield `NULL`.
 #[must_use]
 pub fn property(graph: &Graph, node: NodeRef, prop: &str) -> CypherValue {
     match prop {
@@ -319,12 +319,18 @@ fn document_property(graph: &Graph, id: UriId, prop: &str) -> CypherValue {
         return CypherValue::Null;
     };
 
+    // Non-`file://` URIs (the synthetic built-in document) have no file path, so `path`/`name` fall
+    // back to the raw URI.
     match prop {
+        // Full document URI, e.g. `file:///app/models/user.rb`.
         "uri" => CypherValue::Str(document.uri().to_string()),
-        "path" | "name" => {
-            let uri = document.uri();
-            CypherValue::Str(uri.rsplit('/').next().unwrap_or(uri).to_string())
-        }
+        // File-system path, e.g. `/app/models/user.rb`.
+        "path" => CypherValue::Str(document.file_path().map_or_else(
+            || document.uri().to_string(),
+            |path| path.to_string_lossy().into_owned(),
+        )),
+        // Base file name, e.g. `user.rb`.
+        "name" => CypherValue::Str(document.file_name().unwrap_or_else(|| document.uri().to_string())),
         _ => CypherValue::Null,
     }
 }

rust/rubydex/src/query/cypher/schema_info.rs

@@ -218,7 +218,12 @@ const PROPERTIES: &[PropInfo] = &[
     PropInfo {
         node_type: "Document",
         property: "path",
-        description: "Basename of the document URI",
+        description: "File system path of the document",
+    },
+    PropInfo {
+        node_type: "Document",
+        property: "name",
+        description: "Base file name of the document",
     },
 ];
 

rust/rubydex/src/query/cypher/tests.rs

@@ -188,3 +188,19 @@ fn unknown_relationship_type_errors() {
     let parsed = parse("MATCH (a)-[:BOGUS]->(b) RETURN a").unwrap();
     assert!(execute(&graph, &parsed).is_err());
 }
+
+#[test]
+fn document_uri_path_and_name_are_distinct() {
+    let graph = fixture_graph();
+    let result = run(
+        &graph,
+        "MATCH (d:Document) WHERE d.uri = 'file:///zoo.rb' RETURN d.uri, d.path, d.name",
+    );
+    assert_eq!(
+        result.columns,
+        vec!["d.uri".to_string(), "d.path".to_string(), "d.name".to_string()]
+    );
+    assert_eq!(column_strings(&result, 0), vec!["file:///zoo.rb".to_string()]);
+    assert_eq!(column_strings(&result, 1), vec!["/zoo.rb".to_string()]);
+    assert_eq!(column_strings(&result, 2), vec!["zoo.rb".to_string()]);
+}