theirongolddev/gitlore
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: Remove redundant doc comments throughout codebase

Browse Source 
Removes module-level doc comments (//! lines) and excessive inline doc
comments that were duplicating information already evident from:
- Function/struct names (self-documenting code)
- Type signatures (the what is clear from types)
- Implementation context (the how is clear from code)

Affected modules:
- cli/* - Removed command descriptions duplicating clap help text
- core/* - Removed module headers and obvious function docs
- documents/* - Removed extractor/regenerator/truncation docs
- embedding/* - Removed pipeline and chunking docs
- gitlab/* - Removed client and transformer docs (kept type definitions)
- ingestion/* - Removed orchestrator and ingestion docs
- search/* - Removed FTS and vector search docs

Philosophy: Code should be self-documenting. Comments should explain
"why" (business decisions, non-obvious constraints) not "what" (which
the code itself shows). This change reduces noise and maintenance burden
while keeping the codebase just as understandable.

Retains comments for:
- Non-obvious business logic
- Important safety invariants
- Complex algorithm explanations
- Public API boundaries where generated docs matter

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Taylor Eernisse
2026-02-05 00:04:32 -05:00
parent 976ad92ef0
commit 65583ed5d6
57 changed files with 143 additions and 1693 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
src/core/lock.rs
View File

@@ -1,7 +1,3 @@
//! Crash-safe single-flight lock using heartbeat pattern.
//!
//! Prevents concurrent sync operations and allows recovery from crashed processes.
use rusqlite::{Connection, TransactionBehavior};
use std::path::PathBuf;
use std::sync::Arc;
@@ -15,17 +11,14 @@ use super::db::create_connection;
use super::error::{LoreError, Result};
use super::time::{ms_to_iso, now_ms};
/// Maximum consecutive heartbeat failures before signaling error.
const MAX_HEARTBEAT_FAILURES: u32 = 3;
/// Lock configuration options.
pub struct LockOptions {
pub name: String,
pub stale_lock_minutes: u32,
pub heartbeat_interval_seconds: u32,
}
/// App lock with heartbeat for crash recovery.
pub struct AppLock {
conn: Connection,
db_path: PathBuf,
@@ -40,7 +33,6 @@ pub struct AppLock {
}
impl AppLock {
/// Create a new app lock instance.
pub fn new(conn: Connection, options: LockOptions) -> Self {
let db_path = conn.path().map(PathBuf::from).unwrap_or_default();
@@ -58,23 +50,17 @@ impl AppLock {
}
}
/// Check if heartbeat has failed (indicates lock may be compromised).
pub fn is_heartbeat_healthy(&self) -> bool {
!self.heartbeat_failed.load(Ordering::SeqCst)
}
/// Attempt to acquire the lock atomically.
///
/// Returns Ok(true) if lock acquired, Err if lock is held by another active process.
pub fn acquire(&mut self, force: bool) -> Result<bool> {
let now = now_ms();
// Use IMMEDIATE transaction to prevent race conditions
let tx = self
.conn
.transaction_with_behavior(TransactionBehavior::Immediate)?;
// Check for existing lock within the transaction
let existing: Option<(String, i64, i64)> = tx
.query_row(
"SELECT owner, acquired_at, heartbeat_at FROM app_locks WHERE name = ?",
@@ -85,7 +71,6 @@ impl AppLock {
match existing {
None => {
// No lock exists, acquire it
tx.execute(
"INSERT INTO app_locks (name, owner, acquired_at, heartbeat_at) VALUES (?, ?, ?, ?)",
(&self.name, &self.owner, now, now),
@@ -96,7 +81,6 @@ impl AppLock {
let is_stale = now - heartbeat_at > self.stale_lock_ms;
if is_stale || force {
// Lock is stale or force override, take it
tx.execute(
"UPDATE app_locks SET owner = ?, acquired_at = ?, heartbeat_at = ? WHERE name = ?",
(&self.owner, now, now, &self.name),
@@ -108,13 +92,11 @@ impl AppLock {
"Lock acquired (override)"
);
} else if existing_owner == self.owner {
// Re-entrant, update heartbeat
tx.execute(
"UPDATE app_locks SET heartbeat_at = ? WHERE name = ?",
(now, &self.name),
)?;
} else {
// Lock held by another active process - rollback and return error
drop(tx);
return Err(LoreError::DatabaseLocked {
owner: existing_owner,
@@ -124,20 +106,17 @@ impl AppLock {
}
}
// Commit the transaction atomically
tx.commit()?;
self.start_heartbeat();
Ok(true)
}
/// Release the lock.
pub fn release(&mut self) {
if self.released.swap(true, Ordering::SeqCst) {
return; // Already released
return;
}
// Stop heartbeat thread
if let Some(handle) = self.heartbeat_handle.take() {
let _ = handle.join();
}
@@ -150,7 +129,6 @@ impl AppLock {
info!(owner = %self.owner, "Lock released");
}
/// Start the heartbeat thread to keep the lock alive.
fn start_heartbeat(&mut self) {
let name = self.name.clone();
let owner = self.owner.clone();
@@ -161,11 +139,10 @@ impl AppLock {
let db_path = self.db_path.clone();
if db_path.as_os_str().is_empty() {
return; // In-memory database, skip heartbeat
return;
}
self.heartbeat_handle = Some(thread::spawn(move || {
// Open a new connection with proper pragmas
let conn = match create_connection(&db_path) {
Ok(c) => c,
Err(e) => {
@@ -175,11 +152,9 @@ impl AppLock {
}
};
// Poll frequently for early exit, but only update heartbeat at full interval
const POLL_INTERVAL: Duration = Duration::from_millis(100);
loop {
// Sleep in small increments, checking released flag frequently
let mut elapsed = Duration::ZERO;
while elapsed < interval {
thread::sleep(POLL_INTERVAL);
@@ -189,7 +164,6 @@ impl AppLock {
}
}
// Check once more after full interval elapsed
if released.load(Ordering::SeqCst) {
break;
}
@@ -203,12 +177,10 @@ impl AppLock {
match result {
Ok(rows_affected) => {
if rows_affected == 0 {
// Lock was stolen or deleted
warn!(owner = %owner, "Heartbeat failed: lock no longer held");
heartbeat_failed.store(true, Ordering::SeqCst);
break;
}
// Reset failure count on success
failure_count.store(0, Ordering::SeqCst);
debug!(owner = %owner, "Heartbeat updated");
}