feat(search): provide suggestions for unknown libraries

Introduces fuzzy search using `fuse.js` to suggest similar library names when a requested library is not found during a search operation.

This improves the user experience by guiding users towards potentially correct library names instead of just returning an empty result or a generic error.

The `DocumentManagementService` now includes a `validateLibraryExists` method that performs this check and suggestion generation. The `SearchTool` utilizes this method before attempting to find versions or perform the actual search.

Fixes #12

Author: arabold

package-lock.json

@@ -44,6 +44,7 @@
     "dompurify": "^3.2.4",
     "dotenv": "^16.4.7",
     "drizzle-orm": "^0.41.0",
+    "fuse.js": "^7.1.0",
     "jsdom": "^26.0.0",
     "langchain": "0.3.19",
     "pg": "^8.14.0",
@@ -65,6 +66,7 @@
     "@semantic-release/npm": "^12.0.1",
     "@types/better-sqlite3": "^7.6.12",
     "@types/jsdom": "~21.1.7",
+    "@types/lint-staged": "~13.3.0",
     "@types/node": "^20.17.23",
     "@types/pg": "~8.11.11",
     "@types/semver": "^7.5.8",

package.json

@@ -1,6 +1,6 @@
 import { Document } from "@langchain/core/documents";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { VersionNotFoundError } from "../tools/errors";
+import { LibraryNotFoundError, VersionNotFoundError } from "../tools/errors";
 import { DocumentManagementService } from "./DocumentManagementService";
 import { StoreError } from "./errors";
 
@@ -413,4 +413,98 @@ describe("DocumentManagementService", () => {
       expect(mockRetriever.search).toHaveBeenCalledWith(library, "", query, 10);
     });
   });
+
+  describe("validateLibraryExists", () => {
+    const library = "test-lib";
+    const existingLibraries = [
+      { library: "test-lib", versions: [{ version: "1.0.0", indexed: true }] },
+      { library: "another-lib", versions: [{ version: "2.0.0", indexed: true }] },
+      { library: "react", versions: [] },
+    ];
+
+    it("should resolve successfully if versioned documents exist", async () => {
+      mockStore.queryUniqueVersions.mockResolvedValue(["1.0.0"]); // Has versioned docs
+      mockStore.checkDocumentExists.mockResolvedValue(false); // No unversioned docs
+
+      await expect(docService.validateLibraryExists(library)).resolves.toBeUndefined();
+      expect(mockStore.queryUniqueVersions).toHaveBeenCalledWith(library.toLowerCase());
+      expect(mockStore.checkDocumentExists).toHaveBeenCalledWith(
+        library.toLowerCase(),
+        "",
+      );
+    });
+
+    it("should resolve successfully if only unversioned documents exist", async () => {
+      mockStore.queryUniqueVersions.mockResolvedValue([]); // No versioned docs
+      mockStore.checkDocumentExists.mockResolvedValue(true); // Has unversioned docs
+
+      await expect(docService.validateLibraryExists(library)).resolves.toBeUndefined();
+      expect(mockStore.queryUniqueVersions).toHaveBeenCalledWith(library.toLowerCase());
+      expect(mockStore.checkDocumentExists).toHaveBeenCalledWith(
+        library.toLowerCase(),
+        "",
+      );
+    });
+
+    it("should throw LibraryNotFoundError if library does not exist (no suggestions)", async () => {
+      const nonExistentLibrary = "non-existent-lib";
+      mockStore.queryUniqueVersions.mockResolvedValue([]);
+      mockStore.checkDocumentExists.mockResolvedValue(false);
+      mockStore.queryLibraryVersions.mockResolvedValue(new Map()); // No libraries exist at all
+
+      await expect(docService.validateLibraryExists(nonExistentLibrary)).rejects.toThrow(
+        LibraryNotFoundError,
+      );
+
+      const error = await docService
+        .validateLibraryExists(nonExistentLibrary)
+        .catch((e) => e);
+      expect(error).toBeInstanceOf(LibraryNotFoundError);
+      expect(error.requestedLibrary).toBe(nonExistentLibrary);
+      expect(error.suggestions).toEqual([]);
+      expect(mockStore.queryLibraryVersions).toHaveBeenCalled(); // Ensure it tried to get suggestions
+    });
+
+    it("should throw LibraryNotFoundError with suggestions if library does not exist", async () => {
+      const misspelledLibrary = "reac"; // Misspelled 'react'
+      mockStore.queryUniqueVersions.mockResolvedValue([]);
+      mockStore.checkDocumentExists.mockResolvedValue(false);
+      // Mock listLibraries to return existing libraries
+      const mockLibraryMap = new Map(
+        existingLibraries.map((l) => [
+          l.library,
+          new Set(l.versions.map((v) => v.version)),
+        ]),
+      );
+      mockStore.queryLibraryVersions.mockResolvedValue(mockLibraryMap);
+
+      await expect(docService.validateLibraryExists(misspelledLibrary)).rejects.toThrow(
+        LibraryNotFoundError,
+      );
+
+      const error = await docService
+        .validateLibraryExists(misspelledLibrary)
+        .catch((e) => e);
+      expect(error).toBeInstanceOf(LibraryNotFoundError);
+      expect(error.requestedLibrary).toBe(misspelledLibrary);
+      expect(error.suggestions).toEqual(["react"]); // Expect 'react' as suggestion
+      expect(mockStore.queryLibraryVersions).toHaveBeenCalled();
+    });
+
+    it("should handle case insensitivity", async () => {
+      const libraryUpper = "TEST-LIB";
+      mockStore.queryUniqueVersions.mockResolvedValue(["1.0.0"]); // Mock store uses lowercase
+      mockStore.checkDocumentExists.mockResolvedValue(false);
+
+      // Should still resolve because the service normalizes the input
+      await expect(
+        docService.validateLibraryExists(libraryUpper),
+      ).resolves.toBeUndefined();
+      expect(mockStore.queryUniqueVersions).toHaveBeenCalledWith(library.toLowerCase());
+      expect(mockStore.checkDocumentExists).toHaveBeenCalledWith(
+        library.toLowerCase(),
+        "",
+      );
+    });
+  });
 });

src/store/DocumentManagementService.test.ts

@@ -1,10 +1,11 @@
 import { mkdirSync } from "node:fs";
 import path from "node:path";
 import type { Document } from "@langchain/core/documents";
+import Fuse from "fuse.js";
 import semver from "semver";
 import { GreedySplitter, SemanticMarkdownSplitter } from "../splitter";
 import type { ContentChunk, DocumentSplitter } from "../splitter/types";
-import { VersionNotFoundError } from "../tools";
+import { LibraryNotFoundError, VersionNotFoundError } from "../tools";
 import { logger } from "../utils/logger";
 import { DocumentRetrieverService } from "./DocumentRetrieverService";
 import { DocumentStore } from "./DocumentStore";
@@ -46,18 +47,65 @@ export class DocumentManagementService {
     this.splitter = greedySplitter;
   }
 
+  /**
+   * Initializes the underlying document store.
+   */
   async initialize(): Promise<void> {
     await this.store.initialize();
   }
 
+  /**
+   * Shuts down the underlying document store.
+   */
+
   async shutdown(): Promise<void> {
     logger.info("🔌 Shutting down store manager");
     await this.store.shutdown();
   }
 
   /**
-   * Returns a list of all available versions for a library.
-   * Only returns versions that follow semver format.
+   * Validates if a library exists in the store (either versioned or unversioned).
+   * Throws LibraryNotFoundError with suggestions if the library is not found.
+   * @param library The name of the library to validate.
+   * @throws {LibraryNotFoundError} If the library does not exist.
+   */
+  async validateLibraryExists(library: string): Promise<void> {
+    logger.info(`🔎 Validating existence of library: ${library}`);
+    const normalizedLibrary = library.toLowerCase(); // Ensure consistent casing
+
+    // Check for both versioned and unversioned documents
+    const versions = await this.listVersions(normalizedLibrary);
+    const hasUnversioned = await this.exists(normalizedLibrary, ""); // Check explicitly for unversioned
+
+    if (versions.length === 0 && !hasUnversioned) {
+      logger.warn(`⚠️ Library '${library}' not found.`);
+
+      // Library doesn't exist, fetch all libraries to provide suggestions
+      const allLibraries = await this.listLibraries();
+      const libraryNames = allLibraries.map((lib) => lib.library);
+
+      let suggestions: string[] = [];
+      if (libraryNames.length > 0) {
+        const fuse = new Fuse(libraryNames, {
+          // Configure fuse.js options if needed (e.g., threshold)
+          // isCaseSensitive: false, // Handled by normalizing library names
+          // includeScore: true,
+          threshold: 0.4, // Adjust threshold for desired fuzziness (0=exact, 1=match anything)
+        });
+        const results = fuse.search(normalizedLibrary);
+        // Take top 3 suggestions
+        suggestions = results.slice(0, 3).map((result) => result.item);
+        logger.info(`🔍 Found suggestions: ${suggestions.join(", ")}`);
+      }
+
+      throw new LibraryNotFoundError(library, suggestions);
+    }
+
+    logger.info(`✅ Library '${library}' confirmed to exist.`);
+  }
+
+  /**
+   * Returns a list of all available semantic versions for a library.
    */
   async listVersions(library: string): Promise<LibraryVersion[]> {
     const versions = await this.store.queryUniqueVersions(library);

src/store/DocumentManagementService.ts

@@ -3,7 +3,7 @@ import type { DocumentManagementService } from "../store";
 import type { StoreSearchResult } from "../store/types";
 import { logger } from "../utils/logger";
 import { SearchTool, type SearchToolOptions } from "./SearchTool";
-import { VersionNotFoundError } from "./errors";
+import { LibraryNotFoundError, VersionNotFoundError } from "./errors";
 
 // Mock dependencies
 vi.mock("../store");
@@ -17,6 +17,7 @@ describe("SearchTool", () => {
     vi.resetAllMocks();
 
     mockDocService = {
+      validateLibraryExists: vi.fn(),
       findBestVersion: vi.fn(),
       searchStore: vi.fn(),
     };
@@ -169,6 +170,41 @@ describe("SearchTool", () => {
     );
   });
 
+  it("should return error structure with suggestions when LibraryNotFoundError occurs", async () => {
+    const options: SearchToolOptions = { ...baseOptions };
+    const suggestions = ["test-lib-correct", "another-test-lib"];
+    const error = new LibraryNotFoundError("test-lib", suggestions);
+    (mockDocService.validateLibraryExists as Mock).mockRejectedValue(error);
+
+    const result = await searchTool.execute(options);
+
+    expect(mockDocService.validateLibraryExists).toHaveBeenCalledWith("test-lib");
+    expect(mockDocService.findBestVersion).not.toHaveBeenCalled();
+    expect(mockDocService.searchStore).not.toHaveBeenCalled();
+    expect(result.results).toEqual([]);
+    expect(result.error).toBeDefined();
+    expect(result.error?.message).toContain("Library 'test-lib' not found.");
+    expect(result.error?.suggestions).toEqual(suggestions);
+    expect(result.error?.availableVersions).toBeUndefined(); // Ensure version info isn't present
+    expect(logger.info).toHaveBeenCalledWith(
+      // Changed from warn to info to match implementation
+      expect.stringContaining("Library not found"),
+    );
+  });
+
+  it("should re-throw unexpected errors from validateLibraryExists", async () => {
+    const options: SearchToolOptions = { ...baseOptions };
+    const unexpectedError = new Error("Validation DB connection failed");
+    (mockDocService.validateLibraryExists as Mock).mockRejectedValue(unexpectedError);
+
+    await expect(searchTool.execute(options)).rejects.toThrow(
+      "Validation DB connection failed",
+    );
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.stringContaining("Search failed: Validation DB connection failed"),
+    );
+  });
+
   it("should re-throw unexpected errors from searchStore", async () => {
     const options: SearchToolOptions = {
       ...baseOptions,

src/tools/SearchTool.test.ts

@@ -1,7 +1,7 @@
 import type { DocumentManagementService } from "../store";
 import type { StoreSearchResult } from "../store/types";
 import { logger } from "../utils/logger";
-import { VersionNotFoundError } from "./errors";
+import { LibraryNotFoundError, VersionNotFoundError } from "./errors";
 
 export interface SearchToolOptions {
   library: string;
@@ -11,12 +11,15 @@ export interface SearchToolOptions {
   exactMatch?: boolean;
 }
 
+export interface SearchToolResultError {
+  message: string;
+  availableVersions?: Array<{ version: string; indexed: boolean }>; // Specific to VersionNotFoundError
+  suggestions?: string[]; // Specific to LibraryNotFoundError
+}
+
 export interface SearchToolResult {
   results: StoreSearchResult[];
-  error?: {
-    message: string;
-    availableVersions: Array<{ version: string; indexed: boolean }>;
-  };
+  error?: SearchToolResultError;
 }
 
 /**
@@ -39,6 +42,10 @@ export class SearchTool {
     );
 
     try {
+      // 1. Validate library exists first
+      await this.docService.validateLibraryExists(library);
+
+      // 2. Proceed with version finding and searching
       let versionToSearch: string | null | undefined = version;
 
       if (!exactMatch) {
@@ -66,6 +73,16 @@ export class SearchTool {
 
       return { results };
     } catch (error) {
+      if (error instanceof LibraryNotFoundError) {
+        logger.info(`ℹ️ Library not found: ${error.message}`);
+        return {
+          results: [],
+          error: {
+            message: error.message,
+            suggestions: error.suggestions,
+          },
+        };
+      }
       if (error instanceof VersionNotFoundError) {
         logger.info(`ℹ️ Version not found: ${error.message}`);
         return {