Expand description
§raz-override
Override management system for raz with stable key generation that doesn’t depend on exact cursor position.
§Features
- Stable Key Generation: Uses function signatures and AST analysis for consistent override keys
- Fuzzy Function Detection: Intelligently detects function boundaries even with imprecise cursor positions
- Fallback Resolution: Multi-level key resolution for finding the best matching override
- Tree-sitter Integration: Accurate AST-based function signature extraction
- Debug Commands: Comprehensive tools for inspecting and managing overrides
- Override Preview: See changes before applying them
- Export/Import: Backup and share override configurations
§Key Components
§Override Key Generation
- Function signature-based keys (e.g.,
fn:test_my_function) - File + line range keys for non-function contexts
- Hierarchical fallback resolution
§Function Detection
- Tree-sitter based AST analysis
- Fuzzy boundary detection within tolerance
- Support for nested functions and closures
§Override Resolution
- Try exact function signature match
- Try file + expanded line range
- Try file-level override
- Try workspace default
§Deferred Save System
The override system implements a deferred save pattern - overrides are only persisted after successful command execution. This prevents failed configurations from polluting the override store.
§How It Works
- Override data is prepared but not saved immediately
- Command is executed with the override applied
- Only if the command succeeds is the override saved to config
- Failed commands leave no persistent configuration
§Usage Examples
§Library Usage
use raz_override::{SmartOverrideParser, OverrideSystem};
use raz_config::CommandOverride;
use std::path::Path;
// Parse runtime overrides
let parser = SmartOverrideParser::new("test");
let overrides = parser.parse("RUST_BACKTRACE=full --release -- --exact");
// Create override system for workspace
let workspace_path = Path::new(".");
let mut override_system = OverrideSystem::new(&workspace_path)?;
// Get function context and save override (deferred save pattern)
let file_path = Path::new("src/lib.rs");
let function_context = override_system.get_function_context(file_path, 24, Some(0))?;
let override_key = override_system.generate_key(&function_context)?;
// Create a command override
let mut command_override = CommandOverride::new("cargo".to_string());
command_override.cargo_options.push("--release".to_string());
// Only save after successful execution
let command_succeeded = true; // Set based on actual command execution
if command_succeeded {
override_system.save_override_with_validation(
override_key,
command_override,
&function_context,
"test"
)?;
}§Library API
The crate provides comprehensive APIs for override management:
- List and inspect overrides
- Debug override resolution
- Export/import functionality
- Migration from legacy formats
- Statistics and reporting
For CLI usage, see the raz-cli documentation.
§Migration from Legacy Overrides
The crate includes migration functionality for converting legacy cursor position-based overrides to the new stable key format. Migration can be performed programmatically through the API.
See migration-guide.md for the migration format details.
Re-exports§
pub use backup::BackupInfo;pub use backup::BackupManager;pub use cli::OverrideCli;pub use detector::FunctionDetector;pub use detector::FunctionInfo;pub use error::OverrideError;pub use error::Result;pub use inspector::OverrideInspector;pub use key::FunctionContext;pub use key::OverrideKey;pub use migration::MigrationReport;pub use migration::OverrideMigrator;pub use parser::OptionValue;pub use parser::OverrideOperator;pub use parser::OverrideParser;pub use parser::ParsedOverride;pub use parser::ParsedOverrides;pub use parser::SmartOverrideParser;pub use parser::parse_override;pub use parser::parse_override_to_command;pub use preview::OverridePreview;pub use preview::PreviewChange;pub use resolver::OverrideResolver;pub use resolver::ResolutionStrategy;pub use storage::OverrideStorage;pub use system::OverrideSystem;pub use system::PreviewParams;
Modules§
- backup
- cli
- detector
- error
- inspector
- key
- migration
- parser
- Override parsing functionality
- preview
- resolver
- storage
- system