feat: docid system — 6-char hash IDs for quick file reference

Every indexed file gets a deterministic #docid (SHA-256 of path,
truncated to 6 hex chars). Shown in search results. Supports
direct lookup via 'engraph get #abc123'.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: devwhodevs

src/docid.rs

@@ -0,0 +1,40 @@
+use sha2::{Digest, Sha256};
+
+/// Generate a 6-character hex docid from a file path.
+/// Deterministic: same path always produces same docid.
+pub fn generate_docid(path: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(path.as_bytes());
+    let hash = hasher.finalize();
+    format!("{:02x}{:02x}{:02x}", hash[0], hash[1], hash[2])
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_generate_docid_length_and_hex() {
+        let docid = generate_docid("notes/test.md");
+        assert_eq!(docid.len(), 6, "docid should be 6 characters");
+        assert!(
+            docid.chars().all(|c| c.is_ascii_hexdigit()),
+            "docid should be all hex chars, got: {}",
+            docid
+        );
+    }
+
+    #[test]
+    fn test_docid_deterministic() {
+        let a = generate_docid("notes/test.md");
+        let b = generate_docid("notes/test.md");
+        assert_eq!(a, b, "same path must produce same docid");
+    }
+
+    #[test]
+    fn test_docid_unique() {
+        let a = generate_docid("notes/a.md");
+        let b = generate_docid("notes/b.md");
+        assert_ne!(a, b, "different paths should produce different docids");
+    }
+}

src/indexer.rs

@@ -10,6 +10,7 @@ use tracing::info;
 
 use crate::chunker::{chunk_markdown, split_oversized_chunks};
 use crate::config::Config;
+use crate::docid::generate_docid;
 use crate::embedder::Embedder;
 use crate::hnsw::HnswIndex;
 use crate::store::{FileRecord, Store};
@@ -290,8 +291,9 @@ pub fn run_index(vault_path: &Path, config: &Config, rebuild: bool) -> Result<In
     };
 
     for result in &results {
+        let docid = generate_docid(&result.rel_path);
         let file_id =
-            store.insert_file(&result.rel_path, &result.hash, result.mtime, &result.tags)?;
+            store.insert_file(&result.rel_path, &result.hash, result.mtime, &result.tags, &docid)?;
 
         for (heading, snippet, vector, token_count) in &result.chunks {
             let vector_id = next_vector_id;
@@ -450,7 +452,7 @@ mod tests {
         let store = Store::open_memory().unwrap();
         // Insert file with an old/different hash.
         store
-            .insert_file("note.md", "old_hash_that_wont_match", 100, &[])
+            .insert_file("note.md", "old_hash_that_wont_match", 100, &[], &generate_docid("note.md"))
             .unwrap();
 
         let files = walk_vault(root, &[]).unwrap();
@@ -479,10 +481,11 @@ mod tests {
                 &compute_file_hash(&root.join("surviving.md")).unwrap(),
                 100,
                 &[],
+                &generate_docid("surviving.md"),
             )
             .unwrap();
         store
-            .insert_file("deleted.md", "some_hash", 100, &[])
+            .insert_file("deleted.md", "some_hash", 100, &[], &generate_docid("deleted.md"))
             .unwrap();
 
         let files = walk_vault(root, &[]).unwrap();

src/lib.rs

@@ -1,5 +1,6 @@
 pub mod chunker;
 pub mod config;
+pub mod docid;
 pub mod embedder;
 pub mod hnsw;
 pub mod indexer;

src/search.rs

@@ -13,6 +13,7 @@ pub struct SearchResult {
     pub file_path: String,
     pub heading: Option<String>,
     pub snippet: String,
+    pub docid: Option<String>,
 }
 
 /// Run a search query and print results.
@@ -36,9 +37,11 @@ pub fn run_search(query: &str, top_n: usize, json: bool, data_dir: &Path) -> Res
     let mut results = Vec::new();
     for (vector_id, distance) in raw_results {
         if let Some(chunk) = store.get_chunk_by_vector_id(vector_id)? {
-            let file_path = store
-                .get_file_path_by_id(chunk.file_id)?
-                .unwrap_or_else(|| "<unknown>".to_string());
+            // Single query to get both file_path and docid.
+            let (file_path, docid) = match store.get_file_by_id(chunk.file_id)? {
+                Some(f) => (f.path, f.docid),
+                None => ("<unknown>".to_string(), None),
+            };
 
             // Convert cosine distance to similarity score.
             let score = 1.0 - distance;
@@ -53,6 +56,7 @@ pub fn run_search(query: &str, top_n: usize, json: bool, data_dir: &Path) -> Res
                 file_path,
                 heading,
                 snippet: chunk.snippet,
+                docid,
             });
         }
     }
@@ -82,7 +86,7 @@ pub fn run_status(json: bool, data_dir: &Path) -> Result<()> {
 /// Format search results for display (pure function, no I/O).
 pub fn format_results(results: &[SearchResult], json: bool) -> String {
     if results.is_empty() {
-        return "No results found.\n".to_string();
+        return if json { "[]\n".to_string() } else { "No results found.\n".to_string() };
     }
 
     if json {
@@ -98,6 +102,7 @@ pub fn format_results(results: &[SearchResult], json: bool) -> String {
                     "file": r.file_path,
                     "heading": r.heading,
                     "snippet": r.snippet,
+                    "docid": r.docid,
                 })
             })
             .collect();
@@ -109,13 +114,18 @@ pub fn format_results(results: &[SearchResult], json: bool) -> String {
                 Some(h) => format!(" > {h}"),
                 None => String::new(),
             };
+            let docid_part = match &r.docid {
+                Some(d) => format!(" #{d}"),
+                None => String::new(),
+            };
             let snippet = truncate_snippet(&r.snippet, 200);
             out.push_str(&format!(
-                "{:>2}. [{:.2}] {}{}\n    {}\n",
+                "{:>2}. [{:.2}] {}{}{}\n    {}\n",
                 i + 1,
                 r.score,
                 r.file_path,
                 heading_part,
+                docid_part,
                 snippet,
             ));
         }
@@ -219,6 +229,20 @@ mod tests {
             file_path: "foo.md".to_string(),
             heading: Some("## Bar".to_string()),
             snippet: "Some text...".to_string(),
+            docid: Some("ab12cd".to_string()),
+        }];
+        let output = format_results(&results, false);
+        assert_eq!(output, " 1. [0.87] foo.md > ## Bar #ab12cd\n    Some text...\n");
+    }
+
+    #[test]
+    fn test_format_human_result_no_docid() {
+        let results = vec![SearchResult {
+            score: 0.87,
+            file_path: "foo.md".to_string(),
+            heading: Some("## Bar".to_string()),
+            snippet: "Some text...".to_string(),
+            docid: None,
         }];
         let output = format_results(&results, false);
         assert_eq!(output, " 1. [0.87] foo.md > ## Bar\n    Some text...\n");
@@ -231,6 +255,7 @@ mod tests {
             file_path: "foo.md".to_string(),
             heading: Some("## Bar".to_string()),
             snippet: "Some text...".to_string(),
+            docid: Some("ab12cd".to_string()),
         }];
         let output = format_results(&results, true);
         let parsed: Vec<serde_json::Value> = serde_json::from_str(&output).unwrap();
@@ -240,6 +265,7 @@ mod tests {
         assert_eq!(parsed[0]["file"], "foo.md");
         assert_eq!(parsed[0]["heading"], "## Bar");
         assert_eq!(parsed[0]["snippet"], "Some text...");
+        assert_eq!(parsed[0]["docid"], "ab12cd");
     }
 
     #[test]
@@ -248,7 +274,7 @@ mod tests {
         assert_eq!(output, "No results found.\n");
 
         let json_output = format_results(&[], true);
-        assert_eq!(json_output, "No results found.\n");
+        assert_eq!(json_output, "[]\n");
     }
 
     #[test]