ricecoder_completion/
lib.rs

1/// RiceCoder Completion Engine
2///
3/// A language-agnostic code completion engine with pluggable providers for language-specific behavior.
4///
5/// # Architecture
6///
7/// The completion engine follows a layered architecture with external LSP integration:
8///
9/// 1. **External LSP Layer** (Primary): Query external LSP servers (rust-analyzer, tsserver, pylsp, etc.)
10///    for semantic completions when available
11/// 2. **Configuration Layer**: Load and manage language-specific completion configurations
12/// 3. **Context Analysis Layer**: Analyze code context to determine available symbols and expected types
13/// 4. **Completion Generation Layer**: Generate completion suggestions (generic or language-specific)
14/// 5. **Ranking Layer**: Rank completions by relevance, frequency, and recency
15/// 6. **Fallback Layer**: Use internal providers when external LSP is unavailable
16///
17/// # Language Support
18///
19/// The engine supports multiple languages through a pluggable provider system:
20///
21/// - **Rust**: External LSP (rust-analyzer) with fallback to internal provider
22/// - **TypeScript**: External LSP (typescript-language-server) with fallback to internal provider
23/// - **Python**: External LSP (pylsp) with fallback to internal provider
24/// - **Go**: External LSP (gopls) with fallback to internal provider
25/// - **Java**: External LSP (jdtls) with fallback to internal provider
26/// - **Kotlin**: External LSP (kotlin-language-server) with fallback to internal provider
27/// - **Dart**: External LSP (dart-language-server) with fallback to internal provider
28/// - **Generic**: Fallback for unconfigured languages using text-based completion
29///
30/// # External LSP Integration
31///
32/// The completion engine integrates with external LSP servers through the `ExternalLspCompletionProxy`.
33/// When a completion request is made:
34///
35/// 1. If an external LSP server is configured and available, the request is forwarded to it
36/// 2. The external LSP response is transformed to ricecoder's internal model
37/// 3. External completions are merged with internal completions (external takes priority)
38/// 4. If the external LSP is unavailable, the system falls back to internal providers
39///
40/// This provides production-quality semantic completions while maintaining graceful degradation.
41///
42/// # Fallback Providers
43///
44/// **IMPORTANT**: Internal completion providers are now **fallback providers** used only when
45/// external LSP servers are unavailable. They provide basic keyword and pattern-based completions
46/// but lack semantic understanding.
47///
48/// See the `providers` module documentation for details on fallback behavior and limitations.
49///
50/// # Core Components
51///
52/// ## CompletionEngine
53/// The main trait that orchestrates the completion process. Implementations:
54/// - [`GenericCompletionEngine`]: Language-agnostic engine with pluggable providers
55///
56/// ## ContextAnalyzer
57/// Analyzes code context to determine available symbols and expected types. Implementations:
58/// - [`GenericContextAnalyzer`]: Basic text-based context analysis
59/// - [`TreeSitterContextAnalyzer`]: Tree-sitter based scope and symbol detection
60///
61/// ## CompletionGenerator
62/// Generates completion suggestions. Implementations:
63/// - Built-in generic generator for text-based completions
64/// - Language-specific providers (Rust, TypeScript, Python)
65///
66/// ## CompletionRanker
67/// Ranks completions by relevance, frequency, and recency. Implementations:
68/// - [`BasicCompletionRanker`]: Prefix matching and fuzzy matching
69/// - [`AdvancedCompletionRanker`]: Advanced scoring with frequency and recency
70///
71/// ## CompletionProvider
72/// Pluggable providers for language-specific behavior. Implementations:
73/// - [`RustCompletionProvider`]: Rust-specific completions
74/// - [`TypeScriptCompletionProvider`]: TypeScript-specific completions
75/// - [`PythonCompletionProvider`]: Python-specific completions
76/// - [`GenericTextProvider`]: Generic text-based completions
77///
78/// # Ghost Text
79///
80/// Ghost text displays inline suggestions in a lighter color. Components:
81/// - [`GhostTextGenerator`]: Generates ghost text from completions
82/// - [`GhostTextRenderer`]: Renders ghost text in the editor
83/// - [`GhostTextStateManager`]: Manages ghost text state and keyboard handling
84///
85/// # Configuration
86///
87/// Configuration is loaded from YAML/JSON files and supports:
88/// - Language-specific keywords and snippets
89/// - Ranking weights for relevance, frequency, and recency
90/// - Provider references for language-specific behavior
91///
92/// # Example: Basic Usage
93///
94/// ```ignore
95/// use ricecoder_completion::engine::*;
96/// use ricecoder_completion::types::*;
97/// use ricecoder_completion::context::*;
98/// use ricecoder_completion::ranker::*;
99/// use std::sync::Arc;
100///
101/// // Create components
102/// let context_analyzer = Arc::new(GenericContextAnalyzer);
103/// let generator = Arc::new(BasicCompletionGenerator);
104/// let ranker = Arc::new(BasicCompletionRanker::default_weights());
105/// let mut registry = ProviderRegistry::new();
106///
107/// // Create engine
108/// let engine = GenericCompletionEngine::new(
109///     context_analyzer,
110///     generator,
111///     ranker,
112///     registry,
113/// );
114///
115/// // Generate completions
116/// let completions = engine.generate_completions(
117///     "fn main() { let x = ",
118///     Position::new(0, 20),
119///     "rust",
120/// ).await?;
121/// ```
122///
123/// # Example: With Language-Specific Provider
124///
125/// ```ignore
126/// use ricecoder_completion::providers::RustCompletionProvider;
127/// use std::sync::Arc;
128///
129/// // Register Rust provider
130/// let mut registry = ProviderRegistry::new();
131/// registry.register(Arc::new(RustCompletionProvider));
132///
133/// // Now Rust code will use language-specific completions
134/// ```
135///
136/// # Example: Ghost Text
137///
138/// ```ignore
139/// use ricecoder_completion::ghost_text::*;
140/// use ricecoder_completion::types::*;
141///
142/// let generator = BasicGhostTextGenerator;
143/// let completion = CompletionItem::new(
144///     "println!".to_string(),
145///     CompletionItemKind::Macro,
146///     "println!(\"{}\", {})".to_string(),
147/// );
148///
149/// let ghost_text = generator.generate_ghost_text(&completion, Position::new(0, 5))?;
150/// ```
151pub mod config;
152pub mod context;
153pub mod engine;
154pub mod external_lsp_proxy;
155pub mod ghost_text;
156pub mod ghost_text_state;
157pub mod history;
158pub mod language;
159pub mod providers;
160pub mod ranker;
161pub mod types;
162
163// Re-export public types and traits
164pub use config::{ConfigFormat, ConfigLoader, LanguageConfigRegistry};
165pub use context::{ContextAnalyzer, GenericContextAnalyzer, TreeSitterContextAnalyzer};
166pub use engine::{
167    CompletionEngine, CompletionGenerator, CompletionProvider, CompletionRanker,
168    GenericCompletionEngine, ProviderRegistry,
169};
170pub use external_lsp_proxy::{ExternalLspCompletionClient, ExternalLspCompletionProxy};
171pub use ghost_text::{
172    BasicGhostTextGenerator, BasicGhostTextRenderer, GhostTextGenerator, GhostTextRenderer,
173    GhostTextStyle,
174};
175pub use ghost_text_state::{
176    BasicGhostTextKeyHandler, BasicGhostTextStateManager, GhostTextKeyHandler, GhostTextState,
177    GhostTextStateManager, PartialAcceptanceMode,
178};
179pub use history::{CompletionHistory, CompletionUsage};
180pub use language::{Language, LanguageDetector};
181pub use providers::{
182    CompletionProviderFactory, DartCompletionProvider, GenericTextProvider, GoCompletionProvider,
183    JavaCompletionProvider, KotlinCompletionProvider, PythonCompletionProvider,
184    RustCompletionProvider, TypeScriptCompletionProvider,
185};
186pub use ranker::{AdvancedCompletionRanker, BasicCompletionRanker};
187pub use types::*;
188
189// Re-export storage integration
190pub use ricecoder_storage::get_builtin_completion_configs;
191pub use ricecoder_storage::get_completion_config;
ricecoder_completion/lib.rs

ricecoder_completion/
lib.rs
