docs(core): add inline comments throughout core crate

Add concise, high-signal inline comments to function bodies across the
core configuration and utility implementation. Comments explain intent,
edge cases, boundary math, ownership/cloning decisions, and performance
trade-offs rather than restating code behavior.

Key areas covered:
- Config schema (validation, parsing, bounds checking)
- Config storage (file I/O, atomic writes, migration logic)
- Utility functions (time formatting, size formatting, unit conversions)

Author: hate

keyless-core/src/config/schema.rs

@@ -122,14 +122,18 @@ impl FromStr for OutputMode {
     type Err = KeylessError;
 
     fn from_str(s: &str) -> Result<Self, Self::Err> {
+        // Trim whitespace before comparison (handles user input edge cases).
         let v = s.trim();
+        // Case-insensitive comparison for user-friendly parsing.
         if v.eq_ignore_ascii_case("paste") {
             Ok(OutputMode::Paste)
         } else if v.eq_ignore_ascii_case("clipboard") {
             Ok(OutputMode::Clipboard)
         } else if v.eq_ignore_ascii_case("file") {
+            // File mode requires a path; cannot be parsed from string alone.
             Err(KeylessError::Config("file sink requires a path".into()))
         } else {
+            // Unknown sink: return error with the attempted value for debugging.
             Err(KeylessError::Config(format!("unknown sink: {}", v)))
         }
     }
@@ -254,21 +258,26 @@ impl Config {
     /// - Model file existence (done separately at startup for better error messages)
     /// - Hotkey validity (platform-specific, checked during registration)
     pub fn validate(&self) -> KeylessResult<()> {
-        // If outputting to a file, ensure the parent directory exists
+        // If outputting to a file, ensure the parent directory exists.
+        // Check parent() first (returns None for root paths, which we skip).
+        // exists() check prevents silent failures when writing to non-existent directory.
         if let OutputMode::File(path) = &self.output_mode
             && let Some(parent) = path.parent()
             && !parent.exists()
         {
             return Err(KeylessError::InvalidPath(parent.to_path_buf()));
         }
 
-        // Validate language code length (ISO 639-1 = 2 chars, ISO 639-3 = 3 chars)
+        // Validate language code length (ISO 639-1 = 2 chars, ISO 639-3 = 3 chars).
+        // Allow up to 8 chars for future extensions (some codes include script/region suffixes).
+        // Reject empty or excessively long codes (defensive against malformed config).
         if let Some(lang) = &self.language
             && (lang.len() < 2 || lang.len() > 8)
         {
             return Err(KeylessError::Config("invalid language code".into()));
         }
 
+        // Delegate EQ validation; propagate errors via ? operator.
         self.eq.validate()?;
 
         Ok(())

keyless-core/src/config/storage.rs

@@ -19,6 +19,7 @@ pub const CURRENT_VERSION: u32 = 1;
 /// Migrate config to the current version.
 fn migrate_config(mut config: Config) -> Config {
     // Placeholder for future migrations. For now, just ensure version is current.
+    // Update version field if config is from an older schema (enables future migration logic).
     if config.version < CURRENT_VERSION {
         config.version = CURRENT_VERSION;
     }
@@ -27,7 +28,10 @@ fn migrate_config(mut config: Config) -> Config {
 
 /// Compute the cross-platform path for the config file.
 pub fn config_path() -> PathBuf {
+    // Get platform-specific config directory; fallback to current directory if unavailable.
+    // Fallback to "." is defensive (rare edge case where config_dir() fails).
     let base = config_dir().unwrap_or_else(|| PathBuf::from("."));
+    // Join app name and filename to form full path (e.g., ~/.config/keyless/config.json).
     let p = base.join("keyless").join("config.json");
     tracing::trace!(path=%p.display(), "config: computed config path");
     p
@@ -36,20 +40,25 @@ pub fn config_path() -> PathBuf {
 /// Load config from disk (returns None if missing or invalid).
 pub fn load_config() -> Option<Config> {
     let path = config_path();
+    // Read entire file into memory; small file (<10KB) so one-shot read is fine.
     let data = match fs::read(&path) {
         Ok(d) => d,
         Err(e) => {
+            // File missing is expected on first run; log as debug, not error.
             tracing::debug!(path=%path.display(), error=%e, "config: no config file yet");
             return None;
         }
     };
+    // Parse JSON; handle parse errors gracefully (malformed config = None, not panic).
     match serde_json::from_slice::<Config>(&data) {
         Ok(config) => {
+            // Apply migrations if needed (updates version field for older configs).
             let config = migrate_config(config);
             tracing::debug!(path=%path.display(), "config: loaded successfully");
             Some(config)
         }
         Err(e) => {
+            // Log parse error as warning (user may have corrupted config manually).
             tracing::warn!(path=%path.display(), error=%e, "config: failed to parse");
             None
         }
@@ -59,22 +68,29 @@ pub fn load_config() -> Option<Config> {
 /// Save config to disk (atomic-ish: create parent, write file).
 pub fn save_config(config: &Config) -> io::Result<()> {
     let path = config_path();
+    // Create parent directory if missing (e.g., ~/.config/keyless/).
+    // Propagate errors to surface permission issues early (better than silent failure).
     if let Some(dir) = path.parent() {
         // Propagate directory creation errors to surface permission issues early
         fs::create_dir_all(dir)?;
     }
+    // Serialize to pretty-printed JSON (indented, human-readable).
+    // Convert serde error to io::Error for consistent error handling.
     let data = serde_json::to_vec_pretty(config)
         .map_err(|e| io::Error::other(format!("serialize config: {}", e)))?;
-    // Atomic-ish write: write to a temp file then rename
+    // Atomic-ish write: write to temp file then rename (prevents partial writes).
+    // Temp file: config.json.tmp (same directory, atomic rename on most platforms).
     let tmp = path.with_extension("json.tmp");
     fs::write(&tmp, &data)?;
     match fs::rename(&tmp, &path) {
         Ok(()) => {}
         Err(_) => {
-            // Retry once after a short delay (helps on platforms with transient locks)
+            // Retry once after a short delay (helps on platforms with transient locks).
+            // Some filesystems/antivirus temporarily lock files during writes.
             std::thread::sleep(std::time::Duration::from_millis(10));
             if fs::rename(&tmp, &path).is_err() {
-                // Fallback: copy then remove the temp file
+                // Fallback: copy then remove temp file (non-atomic but ensures write succeeds).
+                // Prefer copy over leaving temp file (avoids stale temp files on disk).
                 fs::copy(&tmp, &path)?;
                 let _ = fs::remove_file(&tmp);
             }

keyless-core/src/utils.rs

@@ -3,38 +3,58 @@
 /// Current time in milliseconds since UNIX epoch (saturating to 0 on error).
 pub fn now_millis() -> u64 {
     use std::time::{SystemTime, UNIX_EPOCH};
+    // Get duration since epoch; unwrap_or_default returns Duration::ZERO if system time < epoch.
+    // This handles clock skew edge cases (shouldn't happen on normal systems).
     SystemTime::now()
         .duration_since(UNIX_EPOCH)
         .unwrap_or_default()
+        // Convert to milliseconds (u128), then cast to u64 (truncates if > u64::MAX ms).
+        // u64::MAX ms ≈ 584 million years, so truncation is not a practical concern.
         .as_millis() as u64
 }
 
 /// Format bytes into a human-readable string (KB/MB/GB) with one decimal place.
 pub fn human_size(bytes: u64) -> String {
+    // Binary units (1024-based), not decimal (1000-based); standard for file sizes.
+    // KB: 1024 bytes
+    // MB: 1024 * 1024 bytes
+    // GB: 1024 * 1024 * 1024 bytes
     const KB: f64 = 1024.0;
     const MB: f64 = 1024.0 * 1024.0;
     const GB: f64 = 1024.0 * 1024.0 * 1024.0;
+    // Convert to f64 for division; u64→f64 preserves precision up to 2^53 (plenty for file sizes).
     let b = bytes as f64;
+    // Check largest unit first (descending order) to pick appropriate suffix.
     if b >= GB {
+        // One decimal place via {:.1}; division produces value in GB units.
         format!("{:.1} GB", b / GB)
     } else if b >= MB {
         format!("{:.1} MB", b / MB)
     } else if b >= KB {
         format!("{:.1} KB", b / KB)
     } else {
+        // Bytes: no decimal, use original u64 value (integer bytes).
         format!("{} B", bytes)
     }
 }
 
 /// Format milliseconds as HH:MM:SS or MM:SS if under one hour.
 pub fn fmt_hms(ms: u64) -> String {
+    // Integer division truncates fractional seconds (e.g., 1500ms → 1s, not 1.5s).
     let total_secs = ms / 1000;
+    // Extract hours: total_secs / 3600 (integer division).
     let hours = total_secs / 3600;
+    // Extract minutes: remainder after removing hours, then divide by 60.
+    // Modulo 3600 gives seconds in current hour, divide by 60 gives minutes.
     let mins = (total_secs % 3600) / 60;
+    // Extract seconds: remainder after removing hours and minutes.
     let secs = total_secs % 60;
+    // Conditional formatting: show hours only if > 0 (compact display for short durations).
     if hours > 0 {
+        // HH:MM:SS format; {:02} zero-pads minutes/seconds to 2 digits.
         format!("{}:{:02}:{:02}", hours, mins, secs)
     } else {
+        // MM:SS format (no hours) for durations under 1 hour.
         format!("{:02}:{:02}", mins, secs)
     }
 }