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/// Heading sanitization and normalization helpers
65pub mod heading;
66/// Search index implementation using Tantivy
67pub mod index;
68/// JSON builder helpers for llms.json structures
69pub mod json_builder;
70/// Language filtering for multilingual llms.txt files
71pub mod language_filter;
72/// Anchor remapping utilities between versions
73pub mod mapping;
74/// Tree-sitter based markdown parser
75pub mod parser;
76/// Application profile detection helpers
77pub mod profile;
78/// Performance profiling utilities
79pub mod profiling;
80/// Refresh helpers shared across CLI and MCP
81pub mod refresh;
82/// Built-in registry of known documentation sources
83pub mod registry;
84/// Local filesystem storage for cached documentation
85pub mod storage;
86/// Core data types and structures
87pub mod types;
88/// URL resolver for llms.txt variants
89pub mod url_resolver;
90
91// Re-export commonly used types
92pub use config::{
93    Config, DefaultsConfig, FetchConfig, FollowLinks, IndexConfig, PathsConfig, ToolConfig,
94    ToolMeta,
95};
96pub use error::{Error, Result};
97pub use fetcher::{FetchResult, Fetcher};
98pub use heading::{
99    HeadingPathVariants, HeadingSegmentVariants, normalize_text_for_search, path_variants,
100    segment_variants,
101};
102pub use index::SearchIndex;
103pub use json_builder::build_llms_json;
104pub use language_filter::{FilterStats, LanguageFilter};
105pub use mapping::{build_anchors_map, compute_anchor_mappings};
106pub use parser::{MarkdownParser, ParseResult};
107pub use profiling::{PerformanceMetrics, ResourceMonitor};
108pub use registry::Registry;
109pub use storage::Storage;
110pub use types::*;
blz_core/lib.rs

blz_core/
lib.rs
