blz_core/
lib.rs

1//! # blz-core
2//!
3//! Core functionality for blz - a fast, local search cache for llms.txt documentation.
4//!
5//! This crate provides the foundational components for parsing, storing, and searching
6//! llms.txt documentation files locally. It's designed for speed (sub-10ms search latency),
7//! offline-first usage, and exact line citations.
8//!
9//! ## Architecture
10//!
11//! The crate is organized around several key components:
12//!
13//! - **Configuration**: Global and per-source settings management
14//! - **Parsing**: Tree-sitter based markdown parsing with structured output
15//! - **Types**: Core data structures representing sources, search results, and metadata
16//! - **Error Handling**: Comprehensive error types with categorization and recovery hints
17//!
18//! ## Quick Start
19//!
20//! ```rust
21//! use blz_core::{Config, MarkdownParser, Result};
22//!
23//! // Load global configuration
24//! let config = Config::load()?;
25//!
26//! // Parse markdown content
27//! let mut parser = MarkdownParser::new()?;
28//! let result = parser.parse("# Hello World\n\nThis is content.")?;
29//!
30//! println!("Found {} heading blocks", result.heading_blocks.len());
31//! println!("Generated TOC with {} entries", result.toc.len());
32//! # Ok::<(), blz_core::Error>(())
33//! ```
34//!
35//! ## Performance Characteristics
36//!
37//! - **Parse time**: < 150ms per MB of markdown content
38//! - **Memory usage**: < 2x source document size during parsing
39//! - **Thread safety**: All types are `Send + Sync` where appropriate
40//!
41//! ## Error Handling
42//!
43//! All operations return [`Result<T, Error>`] with structured error information:
44//!
45//! ```rust
46//! use blz_core::{Error, MarkdownParser};
47//!
48//! let mut parser = MarkdownParser::new()?;
49//! match parser.parse("malformed content") {
50//!     Ok(result) => println!("Parsed successfully"),
51//!     Err(Error::Parse(msg)) => eprintln!("Parse error: {}", msg),
52//!     Err(e) if e.is_recoverable() => eprintln!("Recoverable error: {}", e),
53//!     Err(e) => eprintln!("Fatal error: {}", e),
54//! }
55//! # Ok::<(), blz_core::Error>(())
56//! ```
57
58/// Configuration management for global and per-source settings
59pub mod config;
60/// Error types and result aliases
61pub mod error;
62/// HTTP fetching with conditional requests support
63pub mod fetcher;
64/// Search index implementation using Tantivy
65pub mod index;
66/// Anchor remapping utilities between versions
67pub mod mapping;
68/// Tree-sitter based markdown parser
69pub mod parser;
70/// Performance profiling utilities
71pub mod profiling;
72/// Built-in registry of known documentation sources
73pub mod registry;
74/// Local filesystem storage for cached documentation
75pub mod storage;
76/// Core data types and structures
77pub mod types;
78
79// Re-export commonly used types
80pub use config::{
81    Config, DefaultsConfig, FetchConfig, FollowLinks, IndexConfig, PathsConfig, ToolConfig,
82    ToolMeta,
83};
84pub use error::{Error, Result};
85pub use fetcher::{FetchResult, Fetcher, FlavorInfo};
86pub use index::SearchIndex;
87pub use mapping::{build_anchors_map, compute_anchor_mappings};
88pub use parser::{MarkdownParser, ParseResult};
89pub use profiling::{PerformanceMetrics, ResourceMonitor};
90pub use registry::Registry;
91pub use storage::Storage;
92pub use types::*;
blz_core/lib.rs

blz_core/
lib.rs
