fix: resolve cache eviction and filesystem efficiency issues

Issue #9 (MEDIUM): Cache eviction efficiency
- Replaced loading all entries into memory with SQL DELETE ... LIMIT
- Estimate entries to delete based on average size with 20% buffer
- Executes entirely in SQLite without loading data into Node.js
- Prevents memory spikes for large caches
- Added test for efficient eviction behavior

Issue #8 (MEDIUM): Redundant file system calls
- Cache fs.Stats result in translate() method
- Pass cached stats to isFilePath() and translateFile()
- Eliminates duplicate statSync/existsSync calls (3 syscalls → 1)
- Significant performance improvement for file translation
- Updated method signatures to accept optional cached stats

All 1140 tests pass with no regressions.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: sjsyrek

src/cli/commands/translate.ts

@@ -92,22 +92,24 @@ export class TranslateCommand {
 
   /**
    * Translate text, file, or directory
+   * Fix for Issue #8: Cache stats to avoid redundant filesystem calls
    */
   async translate(textOrPath: string, options: TranslateOptions): Promise<string> {
-    // Check if input is a directory
-    // Use statSync() directly to avoid duplicate syscalls (existsSync + statSync)
+    // Check if input is a file/directory with a single stat() call
+    // Cache the stats result to avoid duplicate syscalls later
+    let stats: fs.Stats | null = null;
     try {
-      const stats = fs.statSync(textOrPath);
+      stats = fs.statSync(textOrPath);
       if (stats.isDirectory()) {
         return this.translateDirectory(textOrPath, options);
       }
     } catch {
       // Not a file/directory, treat as text
     }
 
-    // Check if input is a file path
-    if (this.isFilePath(textOrPath)) {
-      return this.translateFile(textOrPath, options);
+    // Check if input is a file path (passing cached stats to avoid re-stating)
+    if (this.isFilePath(textOrPath, stats)) {
+      return this.translateFile(textOrPath, options, stats);
     }
 
     return this.translateText(textOrPath, options);
@@ -117,10 +119,16 @@ export class TranslateCommand {
    * Check if input is a file path
    * Handles cross-platform paths (Windows backslashes and Unix forward slashes)
    * Excludes URLs from being treated as file paths
+   * Fix for Issue #8: Accept cached stats to avoid redundant filesystem calls
    */
-  private isFilePath(input: string): boolean {
-    // Check if file exists
-    if (fs.existsSync(input)) {
+  private isFilePath(input: string, cachedStats?: fs.Stats | null): boolean {
+    // If we have cached stats and it's a file, return true immediately
+    if (cachedStats && cachedStats.isFile()) {
+      return true;
+    }
+
+    // Check if file exists (only if we don't have cached stats)
+    if (!cachedStats && fs.existsSync(input)) {
       return true;
     }
 
@@ -190,8 +198,9 @@ export class TranslateCommand {
 
   /**
    * Translate file
+   * Fix for Issue #8: Accept cached stats to avoid redundant filesystem calls
    */
-  private async translateFile(filePath: string, options: TranslateOptions): Promise<string> {
+  private async translateFile(filePath: string, options: TranslateOptions, cachedStats?: fs.Stats | null): Promise<string> {
     if (!options.output) {
       throw new Error('Output file path is required for file translation. Use --output <path>');
     }
@@ -229,8 +238,13 @@ export class TranslateCommand {
     // Smart routing for text-based files
     // Use text API (cached) for small text files, document API for large files or binaries
     if (this.isTextBasedFile(filePath)) {
-      // Get file size once to avoid duplicate stat() calls
-      const fileSize = this.getFileSize(filePath);
+      // Get file size from cached stats or stat the file (Fix for Issue #8)
+      let fileSize: number | null;
+      if (cachedStats) {
+        fileSize = cachedStats.size;
+      } else {
+        fileSize = this.getFileSize(filePath);
+      }
 
       if (fileSize === null) {
         throw new Error(`File not found or cannot be accessed: ${filePath}`);

src/storage/cache.ts

@@ -258,6 +258,7 @@ export class CacheService {
 
   /**
    * Evict oldest entries if needed to make space
+   * Fix for Issue #9: Use SQL DELETE ... LIMIT to avoid loading all entries into memory
    */
   private evictIfNeeded(newEntrySize: number): void {
     const stats = this.stats();
@@ -270,27 +271,24 @@ export class CacheService {
     // Add a small buffer to ensure we have enough space
     const toFree = stats.totalSize + newEntrySize - this.maxSize + 1;
 
-    // Get oldest entries to delete
-    const stmt = this.db.prepare(`
-      SELECT key, size
-      FROM cache
-      ORDER BY timestamp ASC
-    `);
-
-    const rows = stmt.all() as Array<{ key: string; size: number }>;
-
-    // Delete entries until we've freed enough space
-    let freed = 0;
-    const deleteStmt = this.db.prepare('DELETE FROM cache WHERE key = ?');
-
-    for (const row of rows) {
-      deleteStmt.run(row.key);
-      freed += row.size;
-
-      // Keep deleting until we've freed enough
-      if (freed >= toFree) {
-        break;
-      }
-    }
+    // Estimate how many entries to delete based on average size
+    // This avoids loading all entries into memory for large caches
+    const avgSize = stats.entries > 0 ? stats.totalSize / stats.entries : 1024;
+    const estimatedEntries = Math.ceil(toFree / avgSize);
+
+    // Add 20% buffer to ensure we delete enough entries
+    // This handles cases where oldest entries are larger than average
+    const entriesToDelete = Math.ceil(estimatedEntries * 1.2);
+
+    // Delete oldest entries efficiently using SQL subquery
+    // This executes entirely in SQLite without loading data into Node.js memory
+    this.db.prepare(`
+      DELETE FROM cache
+      WHERE key IN (
+        SELECT key FROM cache
+        ORDER BY timestamp ASC
+        LIMIT ?
+      )
+    `).run(entriesToDelete);
   }
 }

tests/unit/cache-service.test.ts

@@ -269,6 +269,46 @@ describe('CacheService', () => {
       const oldEntry = cacheService.get('key-0');
       expect(oldEntry).toBeNull();
     });
+
+    it('should evict entries efficiently without loading all into memory (Issue #9)', () => {
+      // Create a cache service with small max size for testing
+      const smallCache = new CacheService({
+        dbPath: testCachePath,
+        maxSize: 10 * 1024, // 10KB
+      });
+
+      // Fill cache with many small entries (simulate large cache)
+      for (let i = 0; i < 50; i++) {
+        smallCache.set(`key-${i}`, { text: 'x'.repeat(200) }); // ~200 bytes each
+      }
+
+      const statsBefore = smallCache.stats();
+
+      // Cache should be at capacity
+      expect(statsBefore.totalSize).toBeLessThanOrEqual(statsBefore.maxSize);
+
+      // Add new entry that requires eviction
+      smallCache.set('new-key', { text: 'x'.repeat(1000) }); // ~1KB
+
+      const statsAfter = smallCache.stats();
+
+      // Cache should still be under max size
+      expect(statsAfter.totalSize).toBeLessThanOrEqual(statsAfter.maxSize);
+
+      // New entry should exist
+      const newEntry = smallCache.get('new-key');
+      expect(newEntry).toBeDefined();
+
+      // Oldest entries should be evicted
+      const veryOldEntry = smallCache.get('key-0');
+      expect(veryOldEntry).toBeNull();
+
+      // Some recent entries should still exist
+      const recentEntry = smallCache.get(`key-${49}`);
+      expect(recentEntry).toBeDefined();
+
+      smallCache.close();
+    });
   });
 
   describe('TTL (Time To Live)', () => {