asp/keep
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: document src/services/types.rs, src/modes/common.rs, and src/services/error.rs

Browse Source 
Co-authored-by: aider (openai/andrew/openrouter/sonoma-sky-alpha) <aider@aider.chat>
This commit is contained in:
Andrew Phillips
2025-09-10 15:27:45 -03:00
parent 3ddecc9ed5
commit 9f48d7980b
4 changed files with 99 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
PLAN.md
View File

@@ -233,16 +233,16 @@ Private helpers (e.g., internal `fn` without `pub`) are not flagged, as they don
40. **src/filter_parser.rs** (duplicate of filter_parser.rs)
- Same issues as above.
41. **src/services/types.rs**
41. **src/services/types.rs** [DONE]
- `ItemWithMeta` and `ItemWithContent` structs: Partial.
- `meta_as_map()` method: No doc.
42. **src/modes/common.rs**
42. **src/modes/common.rs** [DONE]
- `OutputFormat` enum: No doc.
- `ColumnType` enum: Partial.
- Functions (`get_meta_from_env`, `format_size`, etc.): Partial.
43. **src/services/error.rs**
43. **src/services/error.rs** [DONE]
- `CoreError` enum: Partial variants.
44. **src/services/compression_service.rs**

74
src/modes/common.rs
View File

@@ -26,17 +26,25 @@ use std::io::IsTerminal;
use std::str::FromStr;
use strum::IntoEnumIterator;
#[derive(Debug, Clone, strum::EnumString, strum::Display, PartialEq)]
#[strum(ascii_case_insensitive)]
/// Enum representing supported output formats for structured data.
///
/// Used to determine how to display lists, info, and status information.
/// Used to determine how to display lists, info, and status information in CLI modes.
/// Defaults to Table for human-readable output; JSON/YAML for machine parsing.
///
/// # Variants
///
/// * `Table` - Formatted table output (default).
/// * `Json` - JSON structured output.
/// * `Yaml` - YAML structured output.
#[derive(Debug, Clone, strum::EnumString, strum::Display, PartialEq)]
#[strum(ascii_case_insensitive)]
///
/// # Examples
///
/// ```
/// use keep::modes::common::OutputFormat;
/// assert_eq!(OutputFormat::from_str("json").unwrap(), OutputFormat::Json);
/// ```
pub enum OutputFormat {
Table,
Json,
@@ -46,16 +54,21 @@ pub enum OutputFormat {
/// Extracts metadata from KEEP_META_* environment variables.
///
/// Scans environment for variables prefixed with KEEP_META_ and extracts
/// key-value pairs for initial item metadata.
/// key-value pairs for initial item metadata. Ignores KEEP_META_PLUGINS.
///
/// # Returns
///
/// `HashMap<String, String>` - Metadata from environment variables.
/// `HashMap<String, String>` - Metadata from environment variables, with keys in uppercase without prefix.
///
/// # Errors
///
/// None; silently ignores non-matching vars and PLUGINS.
///
/// # Examples
///
/// ```
/// # use std::env;
/// # use std::collections::HashMap;
/// env::set_var("KEEP_META_COMMAND", "ls -la");
/// let meta = get_meta_from_env();
/// assert_eq!(meta.get("COMMAND"), Some(&"ls -la".to_string()));
@@ -79,14 +92,16 @@ pub fn get_meta_from_env() -> HashMap<String, String> {
/// Formats a file size in bytes to human-readable or raw format.
///
/// Uses the humansize crate for human-readable output with decimal units (KB, MB, etc.).
///
/// # Arguments
///
/// * `size` - Size in bytes.
/// * `human_readable` - If true, use units like KB, MB; otherwise, raw bytes.
/// * `size` - Size in bytes as u64.
/// * `human_readable` - If true, use units like KB, MB; otherwise, raw bytes as string.
///
/// # Returns
///
/// `String` - Formatted size string.
/// `String` - Formatted size string, e.g., "1.0K" or "1024".
///
/// # Examples
///
@@ -101,9 +116,11 @@ pub fn format_size(size: u64, human_readable: bool) -> String {
}
}
#[derive(Debug, Eq, PartialEq, Clone, strum::EnumIter, strum::Display, strum::EnumString)]
#[strum(ascii_case_insensitive)]
/// Enum representing column types for table display.
///
/// Defines standard and meta columns for list/info modes.
/// Defines standard and meta columns for list/info modes. Supports "meta:<name>" for specific metadata columns.
///
/// # Variants
///
@@ -115,8 +132,14 @@ pub fn format_size(size: u64, human_readable: bool) -> String {
/// * `FilePath` - File path column.
/// * `Tags` - Tags column.
/// * `Meta` - Metadata column (with sub-type via string parsing).
#[derive(Debug, Eq, PartialEq, Clone, strum::EnumIter, strum::Display, strum::EnumString)]
#[strum(ascii_case_insensitive)]
///
/// # Examples
///
/// ```
/// use keep::modes::common::ColumnType;
/// assert_eq!(ColumnType::from_str("id").unwrap(), ColumnType::Id);
/// assert_eq!(ColumnType::from_str("meta:hostname").unwrap(), ColumnType::Meta);
/// ```
pub enum ColumnType {
Id,
Time,
@@ -131,18 +154,22 @@ pub enum ColumnType {
impl ColumnType {
/// Parses a string to a ColumnType, handling "meta:<name>" pattern.
///
/// Supports direct enum variants or "meta:<name>" for metadata columns.
///
/// # Arguments
///
/// * `s` - Input string to parse.
/// * `s` - Input string to parse, e.g., "size" or "meta:hostname".
///
/// # Returns
///
/// * `anyhow::Result<ColumnType>` - Parsed type or error.
/// * `Ok(ColumnType)` - Parsed type on success.
/// * `Err(anyhow::Error)` - If the string doesn't match any variant.
///
/// # Examples
///
/// ```
/// let meta = ColumnType::from_str("meta:hostname")?;
/// use keep::modes::common::ColumnType;
/// let meta = ColumnType::from_str("meta:hostname").unwrap();
/// assert_eq!(meta, ColumnType::Meta);
/// ```
pub fn from_str(s: &str) -> anyhow::Result<Self> {
@@ -244,15 +271,22 @@ pub fn settings_compression_type(cmd: &mut Command, settings: &config::Settings)
/// Parses output format from settings.
///
/// Defaults to `Table` if not specified or invalid.
/// Defaults to `Table` if not specified or invalid. Uses case-insensitive string parsing.
///
/// # Arguments
///
/// * `settings` - Application settings.
/// * `settings` - Application settings with optional output_format field.
///
/// # Returns
///
/// `OutputFormat` - Parsed or default format.
/// `OutputFormat` - Parsed enum variant or Table as default.
///
/// # Examples
///
/// ```
/// let format = settings_output_format(&settings);
/// assert_eq!(format, OutputFormat::Json); // If settings.output_format = Some("json")
/// ```
pub fn settings_output_format(settings: &config::Settings) -> OutputFormat {
settings.output_format
.as_ref()
@@ -262,15 +296,15 @@ pub fn settings_output_format(settings: &config::Settings) -> OutputFormat {
/// Trims trailing whitespace from each line in a multi-line string.
///
/// Useful for cleaning up table output before printing.
/// Useful for cleaning up table output before printing. Preserves newlines but removes spaces/tabs at line ends.
///
/// # Arguments
///
/// * `s` - Input string with potential trailing whitespace.
/// * `s` - Input string with potential trailing whitespace, e.g., "line1 \nline2 ".
///
/// # Returns
///
/// `String` - Cleaned string with trimmed lines.
/// `String` - Cleaned string with trimmed lines, e.g., "line1\nline2".
///
/// # Examples
///

22
src/services/error.rs
View File

@@ -1,22 +1,44 @@
use thiserror::Error;
/// Core error types used across services for consistent error handling.
///
/// This enum centralizes errors from database, I/O, validation, and other operations.
/// It implements Error and Debug for propagation and logging. Use this for all service-level errors.
///
/// # Variants
///
/// * `Database(rusqlite::Error)` - Wraps SQLite errors from queries or transactions.
/// * `Io(std::io::Error)` - Wraps I/O errors from file operations or streams.
/// * `ItemNotFound(i64)` - Specific item not found by ID.
/// * `ItemNotFoundGeneric` - Generic item not found (no ID specified).
/// * `InvalidInput(String)` - User or config input validation failure with message.
/// * `Compression(String)` - Compression/decompression errors with details.
/// * `Other(anyhow::Error)` - Catch-all for other anyhow-wrapped errors.
/// * `Migration(rusqlite_migration::Error)` - Database migration failures.
#[derive(Error, Debug)]
pub enum CoreError {
#[error("Database error: {0}")]
/// Database operation failed.
Database(#[from] rusqlite::Error),
#[error("I/O error: {0}")]
/// File or stream I/O operation failed.
Io(#[from] std::io::Error),
#[error("Item not found with id {0}")]
/// Item with the specified ID does not exist in the database.
ItemNotFound(i64),
#[error("Item not found")]
/// Item does not exist (no specific ID).
ItemNotFoundGeneric,
#[error("Invalid input: {0}")]
/// Input validation failed.
InvalidInput(String),
#[error("Compression error: {0}")]
/// Compression or decompression operation failed.
Compression(String),
#[error(transparent)]
/// Other unexpected error.
Other(#[from] anyhow::Error),
#[error("Migration error: {0}")]
/// Database schema migration failed.
Migration(#[from] rusqlite_migration::Error),
}

21
src/services/types.rs
View File

@@ -3,6 +3,10 @@ use serde::{Deserialize, Serialize};
use std::collections::HashMap;
#[derive(Debug, Clone, Serialize, Deserialize)]
/// Structure representing an item with its associated tags and metadata.
///
/// This is a composite type used for querying and displaying items with their relational data.
/// It combines the core Item with lists of Tags and Meta for complete item representation.
pub struct ItemWithMeta {
/// The core item data.
pub item: Item,
@@ -15,15 +19,30 @@ pub struct ItemWithMeta {
impl ItemWithMeta {
/// Converts metadata to a HashMap for easy lookup.
///
/// This method transforms the vec of Meta into a simple key-value map,
/// useful for quick access by metadata name.
///
/// # Returns
///
/// `HashMap<String, String>` - Metadata as key-value pairs.
/// `HashMap<String, String>` - Metadata as key-value pairs, where keys are names and values are strings.
///
/// # Examples
///
/// ```
/// let item_with_meta = ItemWithMeta { /* ... */ };
/// let meta_map = item_with_meta.meta_as_map();
/// assert_eq!(meta_map.get("hostname"), Some(&"example.com".to_string()));
/// ```
pub fn meta_as_map(&self) -> HashMap<String, String> {
self.meta.iter().cloned().map(|m| (m.name, m.value)).collect()
}
}
#[derive(Debug, Clone, Serialize, Deserialize)]
/// Structure representing an item with its content, tags, and metadata.
///
/// This extends ItemWithMeta by including the actual content bytes, suitable for full item retrieval
/// including binary or text data. Note: For large content, consider streaming alternatives.
pub struct ItemWithContent {
/// Item with associated metadata and tags.
pub item_with_meta: ItemWithMeta,