1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
//! Typed errors for the rustbrain library boundary.
//!
//! CLI code may wrap these in `anyhow`; library consumers should match on
//! [`BrainError`] directly so callers can distinguish “brain missing” from I/O
//! or schema mismatches.
use std::path::PathBuf;
/// Error type returned by all public `rustbrain-core` APIs.
///
/// Variants map roughly to subsystems: storage, mmap cache, FTS, indexing, and
/// portable bundles. Display messages are stable enough for CLI stderr; the
/// enum itself is not yet `#[non_exhaustive]` so minor releases may add variants
/// carefully (consider matching with a wildcard in long-lived apps).
#[derive(Debug, thiserror::Error)]
pub enum BrainError {
/// Filesystem or OS I/O failure.
#[error("I/O error: {0}")]
Io(#[from] std::io::Error),
/// Underlying SQLite / rusqlite error (constraints, SQL, busy, etc.).
#[error("SQLite error: {0}")]
Sqlite(#[from] rusqlite::Error),
/// JSON serialization or deserialization failure (bundles, markers, registry).
#[error("JSON error: {0}")]
Json(#[from] serde_json::Error),
/// No `.brain/db.sqlite` at the expected path (call [`crate::Brain::create`] or `sync` first).
#[error("brain not found at {path}")]
BrainNotFound {
/// Path to the missing `.brain` directory (or parent).
path: PathBuf,
},
/// `.brain` exists but is structurally invalid.
#[error("invalid brain directory: {path}: {reason}")]
InvalidBrain {
/// Path that failed validation.
path: PathBuf,
/// Human-readable reason.
reason: String,
},
/// On-disk schema is newer than this library build (upgrade rustbrain).
#[error("schema version mismatch: found {found}, supported {supported}")]
SchemaVersion {
/// Version found in `schema_meta`.
found: u32,
/// Maximum version this binary understands.
supported: u32,
},
/// CSR `graph.mmap` magic/version/bounds validation failure.
#[error("mmap format error: {0}")]
MmapFormat(String),
/// Empty or illegal full-text query after sanitization.
#[error("FTS query error: {0}")]
FtsQuery(String),
/// Called an API that requires a Cargo feature not enabled for this build.
#[error("feature not enabled: {0}")]
FeatureDisabled(&'static str),
/// Tree-sitter / AST extraction failure.
#[error("AST parse error: {0}")]
Ast(String),
/// Workspace walk / index pipeline failure.
#[error("indexer error: {0}")]
Indexer(String),
/// Portable `.brainbundle` export or import failure.
#[error("export/import error: {0}")]
Bundle(String),
/// Catch-all for rare internal conditions with a message.
#[error("{0}")]
Other(String),
}
impl BrainError {
/// Construct an [`BrainError::Other`] from any displayable message.
pub fn other(msg: impl Into<String>) -> Self {
Self::Other(msg.into())
}
/// Construct an [`BrainError::MmapFormat`] from any displayable message.
pub fn mmap(msg: impl Into<String>) -> Self {
Self::MmapFormat(msg.into())
}
/// Construct an [`BrainError::Indexer`] from any displayable message.
pub fn indexer(msg: impl Into<String>) -> Self {
Self::Indexer(msg.into())
}
/// Construct an [`BrainError::Bundle`] from any displayable message.
pub fn bundle(msg: impl Into<String>) -> Self {
Self::Bundle(msg.into())
}
}
/// Convenient result alias for library APIs: `Result<T, BrainError>`.
pub type Result<T> = std::result::Result<T, BrainError>;