test(cache): add tests for cache invalidation and document schema-aware behavior

- Add test for garbage collection deleting expired files in cache-manager.test.ts
- Add comprehensive tests for TTL-based fetch and schema-aware invalidation in doc-service.test.ts
- Update README to document schema-aware invalidation for cached docs missing anchorIndex

Author: yriveiro

README.md

@@ -70,6 +70,7 @@ fetch_python_doc path="library/asyncio" offset=5000 limit=5000
 - **Doc cache**: 7 days TTL
 - **Location**: `~/.cache/opencode/python-docs/`
 - **Garbage collection**: Runs on startup and server reconnect
+- **Schema-aware invalidation**: Cached docs missing required fields (e.g., anchor index) are refetched even within TTL
 
 ## Development
 

tests/cache-manager.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it } from "bun:test";
-import { existsSync, rmSync } from "node:fs";
+import { existsSync, rmSync, utimesSync } from "node:fs";
 import { tmpdir } from "node:os";
 
 import { CacheManager, type CacheManagerInterface } from "../src/testing";
@@ -89,5 +89,22 @@ describe("CacheManager", () => {
       expect(stats.deleted).toBe(0);
       expect(stats.errors).toBe(0);
     });
+
+    it("should delete expired files", () => {
+      const testIndexPath = cache.getIndexPath("3.12");
+      const testDocPath = cache.getDocPath("3.12", "test");
+      cache.write(testIndexPath, { entries: [] });
+      cache.write(testDocPath, { markdown: "# test", anchorIndex: [], fetchedAt: Date.now() });
+
+      // Set mtime to 2 days ago (longer than any TTL)
+      const oldTime = Date.now() - 2 * 24 * 60 * 60 * 1000;
+      utimesSync(testIndexPath, new Date(oldTime), new Date(oldTime));
+      utimesSync(testDocPath, new Date(oldTime), new Date(oldTime));
+
+      const stats = cache.runGarbageCollection(1000, 1000); // 1 second TTL
+      expect(stats.deleted).toBe(2);
+      expect(existsSync(testIndexPath)).toBe(false);
+      expect(existsSync(testDocPath)).toBe(false);
+    });
   });
 });

tests/doc-service.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it, mock } from "bun:test";
+import type { CachedDoc, CacheManagerInterface, Logger } from "../src/testing";
+import { createDocService } from "../src/testing";
+
+describe("DocService", () => {
+  const mockCache: CacheManagerInterface = {
+    getIndexPath: mock(() => "/mock/index.json"),
+    getDocPath: mock(() => "/mock/doc.json"),
+    isValid: mock(),
+    read: mock(),
+    write: mock(),
+    runGarbageCollection: mock(() => ({ scanned: 0, deleted: 0, errors: 0 })),
+  };
+
+  const mockLogger: Logger = {
+    info: mock(),
+    error: mock(),
+  };
+
+  const docService = createDocService(mockCache, mockLogger);
+
+  describe("getIndex", () => {
+    it("should return cached index if valid", async () => {
+      const cachedIndex = { entries: [] };
+      mockCache.isValid.mockReturnValue(true);
+      mockCache.read.mockReturnValue(cachedIndex);
+
+      const result = await docService.getIndex("3.12");
+
+      expect(result).toEqual(cachedIndex);
+      expect(mockCache.isValid).toHaveBeenCalledWith("/mock/index.json", expect.any(Number));
+      expect(mockCache.read).toHaveBeenCalledWith("/mock/index.json");
+    });
+
+    it("should fetch and cache index if invalid", async () => {
+      const fetchedIndex = { entries: [{ name: "test", path: "test.html", type: "module" }] };
+      mockCache.isValid.mockReturnValue(false);
+      global.fetch = mock(() =>
+        Promise.resolve({
+          ok: true,
+          text: () => Promise.resolve(JSON.stringify(fetchedIndex)),
+        } as Response),
+      );
+
+      const result = await docService.getIndex("3.12");
+
+      expect(result).toEqual(fetchedIndex);
+      expect(mockCache.write).toHaveBeenCalledWith("/mock/index.json", fetchedIndex);
+    });
+  });
+
+  describe("getDoc", () => {
+    it("should return cached doc if valid and has anchorIndex", async () => {
+      const cachedDoc: CachedDoc = {
+        markdown: "# test",
+        anchorIndex: [],
+        fetchedAt: Date.now(),
+      };
+      mockCache.isValid.mockReturnValue(true);
+      mockCache.read.mockReturnValue(cachedDoc);
+
+      const result = await docService.getDoc("3.12", "test");
+
+      expect(result).toEqual({ ...cachedDoc, fromCache: true, path: "test" });
+      expect(mockCache.isValid).toHaveBeenCalledWith("/mock/doc.json", expect.any(Number));
+      expect(mockCache.read).toHaveBeenCalledWith("/mock/doc.json");
+    });
+
+    it("should refetch if cache is invalid", async () => {
+      mockCache.isValid.mockReturnValue(false);
+      global.fetch = mock(() =>
+        Promise.resolve({
+          ok: true,
+          text: () => Promise.resolve("<html><body>test</body></html>"),
+        } as Response),
+      );
+
+      const result = await docService.getDoc("3.12", "test");
+
+      expect(result.fromCache).toBe(false);
+      expect(result.path).toBe("test");
+      expect(result.markdown).toBeDefined();
+      expect(result.anchorIndex).toBeDefined();
+      expect(mockCache.write).toHaveBeenCalled();
+    });
+
+    it("should refetch if cached doc lacks anchorIndex", async () => {
+      const cachedDocWithoutAnchorIndex = {
+        markdown: "# test",
+        fetchedAt: Date.now(),
+        // no anchorIndex
+      };
+      mockCache.isValid.mockReturnValue(true);
+      mockCache.read.mockReturnValue(cachedDocWithoutAnchorIndex);
+      global.fetch = mock(() =>
+        Promise.resolve({
+          ok: true,
+          text: () => Promise.resolve("<html><body>test</body></html>"),
+        } as Response),
+      );
+
+      const result = await docService.getDoc("3.12", "test");
+
+      expect(result.fromCache).toBe(false);
+      expect(result.path).toBe("test");
+      expect(result.markdown).toBeDefined();
+      expect(result.anchorIndex).toBeDefined();
+      expect(mockCache.write).toHaveBeenCalled();
+    });
+  });
+});