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/// Language filtering for multilingual llms.txt files
67pub mod language_filter;
68/// Anchor remapping utilities between versions
69pub mod mapping;
70/// Tree-sitter based markdown parser
71pub mod parser;
72/// Application profile detection helpers
73pub mod profile;
74/// Performance profiling utilities
75pub mod profiling;
76/// Built-in registry of known documentation sources
77pub mod registry;
78/// Local filesystem storage for cached documentation
79pub mod storage;
80/// Core data types and structures
81pub mod types;
82
83// Re-export commonly used types
84pub use config::{
85    Config, DefaultsConfig, FetchConfig, FollowLinks, IndexConfig, PathsConfig, ToolConfig,
86    ToolMeta,
87};
88pub use error::{Error, Result};
89pub use fetcher::{FetchResult, Fetcher};
90pub use index::SearchIndex;
91pub use language_filter::{FilterStats, LanguageFilter};
92pub use mapping::{build_anchors_map, compute_anchor_mappings};
93pub use parser::{MarkdownParser, ParseResult};
94pub use profiling::{PerformanceMetrics, ResourceMonitor};
95pub use registry::Registry;
96pub use storage::Storage;
97pub use types::*;
blz_core/lib.rs

blz_core/
lib.rs
