turbovault_graph/lib.rs
1//! # Link Graph Analysis
2//!
3//! Link graph implementation for Obsidian vault relationships using petgraph.
4//!
5//! Provides:
6//! - Directed graph of vault files and links
7//! - Link resolution (wikilinks, aliases, folder paths)
8//! - Backlink queries
9//! - Related notes discovery (BFS)
10//! - Orphan detection
11//! - Cycle detection
12//! - Graph statistics
13//! - Vault health analysis
14//! - Broken link detection
15//!
16//! ## Quick Start
17//!
18//! ```
19//! use turbovault_graph::LinkGraph;
20//!
21//! // Create a new link graph
22//! let graph = LinkGraph::new();
23//!
24//! // The graph is built by adding VaultFile objects
25//! // and their links will be indexed automatically
26//! println!("Nodes: {}", graph.node_count());
27//! println!("Edges: {}", graph.edge_count());
28//! ```
29//!
30//! ## Core Concepts
31//!
32//! ### Nodes and Edges
33//! - **Nodes**: Represent vault files (notes)
34//! - **Edges**: Represent links between files
35//! - **Directed**: Links flow from source to target
36//!
37//! ### Graph Operations
38//!
39//! - **Backlinks**: Find all notes linking to a given note
40//! - **Forward Links**: Find all notes linked from a given note
41//! - **Related Notes**: Discover related notes through BFS traversal
42//! - **Orphans**: Find isolated notes with no links in or out
43//!
44//! ### Vault Health Metrics
45//!
46//! The health analyzer provides:
47//! - **Health Score**: Overall vault connectivity (0-100)
48//! - **Connectivity Rate**: Percentage of connected notes
49//! - **Link Density**: Ratio of existing links to possible links
50//! - **Broken Links**: Links to non-existent targets
51//! - **Orphaned Notes**: Isolated notes with no relationships
52//!
53//! ## Advanced Usage
54//!
55//! ### Finding Broken Links
56//!
57//! ```
58//! use turbovault_graph::{LinkGraph, HealthAnalyzer};
59//!
60//! let graph = LinkGraph::new();
61//!
62//! // Create health analyzer for comprehensive analysis
63//! let analyzer = HealthAnalyzer::new(&graph);
64//!
65//! // Analyze vault health (includes broken link detection)
66//! if let Ok(report) = analyzer.analyze() {
67//! for broken in &report.broken_links {
68//! println!("Broken: {} -> {}",
69//! broken.source_file.display(),
70//! broken.target
71//! );
72//! }
73//! }
74//! ```
75//!
76//! ### Graph Statistics
77//!
78//! ```
79//! use turbovault_graph::LinkGraph;
80//!
81//! let graph = LinkGraph::new();
82//! println!("Nodes: {}", graph.node_count());
83//! println!("Edges: {}", graph.edge_count());
84//! ```
85//!
86//! ## Modules
87//!
88//! - [`graph`] - Main LinkGraph implementation
89//! - [`health`] - Vault health analysis
90//!
91//! ## Performance Characteristics
92//!
93//! Built on `petgraph` for optimal performance:
94//! - Graph construction: O(n + m) where n = nodes, m = edges
95//! - Backlink queries: O(degree) with caching
96//! - Orphan detection: O(n)
97//! - Cycle detection: O(n + m)
98//! - Health analysis: O(n + m)
99
100pub mod graph;
101pub mod health;
102
103pub use graph::{GraphStats, LinkGraph};
104pub use health::{BrokenLink, HealthAnalyzer, HealthReport};
105pub use turbovault_core::prelude::*;
106
107pub mod prelude {
108 pub use crate::graph::{GraphStats, LinkGraph};
109 pub use crate::health::{BrokenLink, HealthAnalyzer, HealthReport};
110 pub use turbovault_core::prelude::*;
111}