fix: improve search quality and break circular type dependency

Author: vitalis

src/server.ts

@@ -10,6 +10,9 @@ import { handleFetchDocs } from "./tools/fetch-docs.js";
 import { formatUtilitiesList, handleListUtilities } from "./tools/list-utilities.js";
 import { formatSearchResults, handleSearchDocs } from "./tools/search-docs.js";
 import type { Config } from "./utils/config.js";
+import type { EmbedderStatus, IndexingStatus } from "./utils/types.js";
+
+export type { EmbedderStatus, IndexingStatus } from "./utils/types.js";
 
 const { version: SERVER_VERSION } = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf-8"),
@@ -25,16 +28,6 @@ export const TOOL_NAMES = {
   CHECK_STATUS: "check_status",
 } as const;
 
-/**
- * Embedder loading status for observability.
- */
-export type EmbedderStatus = "pending" | "downloading" | "ready" | "failed";
-
-/**
- * Documentation indexing status for observability.
- */
-export type IndexingStatus = "idle" | "indexing" | "complete" | "failed";
-
 /**
  * Server dependencies injected at startup.
  * Embedder may be null if the model is still downloading.

src/storage/search.ts

@@ -116,13 +116,16 @@ export async function hybridSearch(
   // keywordSearch is synchronous but wrapped in Promise.all alongside the async
   // semanticSearch for uniform destructuring. No performance impact — sync
   // functions in Promise.all resolve in the same microtask.
+  // Semantic search benefits from expansion (extra terms help the embedding model).
+  // FTS5 keyword search uses the original query — AND-joining expansion terms
+  // (e.g., "font" AND "size") would over-constrain and hurt recall.
   const [semantic, keyword] = await Promise.all([
     semanticSearch(embedder, chunks, expandedQuery, fetchLimit),
-    keywordSearch(db, expandedQuery, version, fetchLimit),
+    keywordSearch(db, query, version, fetchLimit),
   ]);
 
-  // Boost keyword weight when query contains Tailwind class names (e.g., text-lg, pt-6)
-  const hasClassNames = /\b[a-z]+(?:-[a-z0-9]+)+\b/.test(query);
+  // Boost keyword weight when query contains Tailwind class names (e.g., text-lg, pt-6, -mx-4)
+  const hasClassNames = /\b-?[a-z]+(?:-[a-z0-9]+)+\b/.test(query);
   const weights: FusionWeights = hasClassNames
     ? { semantic: 1.0, keyword: 1.5 }
     : { semantic: 1.0, keyword: 1.0 };

src/tools/check-status.ts

@@ -1,6 +1,6 @@
-import type { EmbedderStatus, IndexingStatus } from "../server.js";
 import type { Database, IndexStatus } from "../storage/database.js";
 import type { TailwindVersion } from "../utils/config.js";
+import type { EmbedderStatus, IndexingStatus } from "../utils/types.js";
 
 /**
  * Input parameters for the check_status MCP tool.

src/tools/search-docs.ts

@@ -1,8 +1,8 @@
 import type { Embedder } from "../pipeline/embedder.js";
-import type { IndexingStatus } from "../server.js";
 import type { Database } from "../storage/database.js";
 import { type SearchResult, hybridSearch } from "../storage/search.js";
 import type { TailwindVersion } from "../utils/config.js";
+import type { IndexingStatus } from "../utils/types.js";
 
 /**
  * Input parameters for the search_docs MCP tool.

src/utils/query-expansion.ts

@@ -6,8 +6,8 @@
  * class prefixes (e.g., "mx-auto") and documentation titles (e.g., "Margin").
  */
 
-/** Regex to detect Tailwind class names: hyphenated lowercase tokens like text-lg, grid-cols-3 */
-const TAILWIND_CLASS_RE = /\b[a-z]+(?:-[a-z0-9]+)+\b/g;
+/** Regex to detect Tailwind class names: hyphenated lowercase tokens like text-lg, grid-cols-3, -mx-4 */
+const TAILWIND_CLASS_RE = /\b-?[a-z]+(?:-[a-z0-9]+)+\b/g;
 
 /** Font size suffixes used by Tailwind's text-{size} utilities */
 const TEXT_SIZE_RE = /^text-(xs|sm|base|lg|xl|\d+xl)$/;
@@ -27,9 +27,15 @@ const PREFIX_MAP = new Map<string, string>([
   ["auto-cols", "grid auto columns"],
   ["auto-rows", "grid auto rows"],
   ["col-span", "grid column"],
+  ["col-start", "grid column"],
+  ["col-end", "grid column"],
   ["row-span", "grid row"],
+  ["row-start", "grid row"],
+  ["row-end", "grid row"],
   ["space-x", "space between horizontal"],
   ["space-y", "space between vertical"],
+  ["gap-x", "gap horizontal"],
+  ["gap-y", "gap vertical"],
   ["min-w", "min-width"],
   ["max-w", "max-width"],
   ["min-h", "min-height"],
@@ -39,6 +45,8 @@ const PREFIX_MAP = new Map<string, string>([
   ["snap-start", "scroll snap align"],
   ["snap-end", "scroll snap align"],
   ["snap-center", "scroll snap align"],
+  ["line-clamp", "line clamp"],
+  ["will-change", "will-change"],
 
   // ── Single-segment prefixes ────────────────────────────────────
   // Spacing
@@ -63,8 +71,11 @@ const PREFIX_MAP = new Map<string, string>([
   ["font", "font"],
   ["tracking", "letter spacing"],
   ["leading", "line height"],
+  ["decoration", "text decoration"],
+  ["whitespace", "whitespace"],
 
   // Flex & Grid
+  ["flex", "flex"],
   ["gap", "gap"],
   ["justify", "justify content"],
   ["items", "align items"],
@@ -107,6 +118,13 @@ const PREFIX_MAP = new Map<string, string>([
   ["clear", "clear"],
   ["object", "object fit"],
   ["overflow", "overflow"],
+  ["break", "word break"],
+
+  // Position
+  ["top", "position"],
+  ["right", "position"],
+  ["bottom", "position"],
+  ["left", "position"],
 
   // Transforms
   ["scale", "scale transform"],
@@ -135,9 +153,15 @@ const PREFIX_MAP = new Map<string, string>([
   ["accent", "accent color"],
   ["caret", "caret color"],
 
-  // Position
+  // Position (z-index, inset)
   ["z", "z-index"],
   ["inset", "position"],
+
+  // Animation
+  ["animate", "animation"],
+
+  // Accessibility
+  ["sr", "screen reader"],
 ]);
 
 /** text- variants that map to text-align */
@@ -224,7 +248,9 @@ export function expandQuery(query: string): string {
   const expansionTerms: string[] = [];
 
   for (const className of classNames) {
-    const terms = resolveExpansion(className);
+    // Strip leading `-` from negative utilities (e.g., -mx-4 → mx-4)
+    const normalized = className.startsWith("-") ? className.slice(1) : className;
+    const terms = resolveExpansion(normalized);
     if (!terms) continue;
 
     for (const term of terms.split(/\s+/)) {

src/utils/types.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared types used across server and tool modules.
+ *
+ * Extracted here to avoid circular imports between server.ts and tool modules.
+ */
+
+/**
+ * Embedder loading status for observability.
+ */
+export type EmbedderStatus = "pending" | "downloading" | "ready" | "failed";
+
+/**
+ * Documentation indexing status for observability.
+ */
+export type IndexingStatus = "idle" | "indexing" | "complete" | "failed";

test/tools/tools.test.ts

@@ -154,6 +154,12 @@ describe("MCP Tool Handlers", () => {
       expect(formatted).toContain("fetch_docs");
     });
 
+    it("returns 'No results found' for empty results when indexed", () => {
+      const result = { results: [], notIndexed: false };
+      const formatted = formatSearchResults(result);
+      expect(formatted).toBe("No results found for this query.");
+    });
+
     it("returns search results for valid query", async () => {
       await indexTestDoc(db, config, PADDING_MDX, "padding");
       const embedder = createMockEmbedder(384);

test/unit/auto-index.test.ts

@@ -1,6 +1,6 @@
 import { mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { maybeAutoIndex } from "../../src/auto-index.js";
 import type { Database } from "../../src/storage/database.js";
 import { createDatabase } from "../../src/storage/database.js";
@@ -89,27 +89,24 @@ describe("maybeAutoIndex", () => {
 
   it("calls onError when indexing fails", async () => {
     // No fixture files and mock fetch to reject
-    const originalFetch = globalThis.fetch;
-    globalThis.fetch = vi.fn().mockRejectedValue(new Error("Network error"));
-
-    try {
-      const embedder = createMockEmbedder(384);
-      const onStart = vi.fn();
-      const onComplete = vi.fn();
-      const onError = vi.fn();
-
-      await maybeAutoIndex(config, db, embedder, {
-        onStart,
-        onComplete,
-        onError,
-      });
-
-      expect(onStart).toHaveBeenCalledOnce();
-      expect(onComplete).not.toHaveBeenCalled();
-      expect(onError).toHaveBeenCalledOnce();
-    } finally {
-      globalThis.fetch = originalFetch;
-    }
+    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("Network error")));
+
+    const embedder = createMockEmbedder(384);
+    const onStart = vi.fn();
+    const onComplete = vi.fn();
+    const onError = vi.fn();
+
+    await maybeAutoIndex(config, db, embedder, {
+      onStart,
+      onComplete,
+      onError,
+    });
+
+    expect(onStart).toHaveBeenCalledOnce();
+    expect(onComplete).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalledOnce();
+
+    vi.unstubAllGlobals();
   });
 
   it("uses the configured default version", async () => {

test/unit/query-expansion.test.ts

@@ -267,5 +267,74 @@ describe("Query Expansion", () => {
       expect(result).toContain("translate");
       expect(result).toContain("transform");
     });
+
+    // ── Negative class names ──────────────────────────────────────
+    it("expands -mx-4 to margin (negative value)", () => {
+      const result = expandQuery("-mx-4 centering");
+      expect(result).toContain("margin");
+    });
+
+    it("expands -translate-x-4 to translate transform (negative value)", () => {
+      const result = expandQuery("-translate-x-4 animation");
+      expect(result).toContain("translate");
+      expect(result).toContain("transform");
+    });
+
+    it("expands -mt-2 to margin (negative value)", () => {
+      const result = expandQuery("-mt-2 spacing");
+      expect(result).toContain("margin");
+    });
+
+    // ── New prefix expansions (round 2) ───────────────────────────
+    it("expands flex-col to flex", () => {
+      const result = expandQuery("flex-col layout");
+      expect(result).toContain("flex");
+    });
+
+    it("expands animate-spin to animation", () => {
+      const result = expandQuery("animate-spin loading");
+      expect(result).toContain("animation");
+    });
+
+    it("expands decoration-wavy to text decoration", () => {
+      const result = expandQuery("decoration-wavy link");
+      expect(result).toContain("text");
+      expect(result).toContain("decoration");
+    });
+
+    it("expands top-4 to position", () => {
+      const result = expandQuery("top-4 absolute");
+      expect(result).toContain("position");
+    });
+
+    it("expands line-clamp-3 to line clamp", () => {
+      const result = expandQuery("line-clamp-3 truncation");
+      expect(result).toContain("line");
+      expect(result).toContain("clamp");
+    });
+
+    it("expands break-words to word break", () => {
+      const result = expandQuery("break-words text");
+      expect(result).toContain("word");
+      expect(result).toContain("break");
+    });
+
+    it("expands sr-only to screen reader", () => {
+      const result = expandQuery("sr-only accessibility");
+      expect(result).toContain("screen");
+      expect(result).toContain("reader");
+    });
+
+    it("expands gap-x-4 to gap horizontal", () => {
+      const result = expandQuery("gap-x-4 grid");
+      expect(result).toContain("gap");
+      expect(result).toContain("horizontal");
+    });
+
+    it("expands col-start-1 to grid column", () => {
+      const result = expandQuery("col-start-1 layout");
+      expect(result).toContain("grid");
+      expect(result).toContain("column");
+    });
   });
 });

test/unit/search.test.ts

@@ -480,4 +480,49 @@ describe("Search", () => {
       expect(results).toHaveLength(5);
     });
   });
+
+  describe("invalidateChunkCache (version-specific)", () => {
+    it("invalidates only the specified version", async () => {
+      const db = await createDatabase(testConfig());
+      const embedder = createMockEmbedder(384);
+
+      // Index a chunk for v3
+      const docId = db.upsertDoc(makeDoc({ version: "v3" }));
+      const emb = await embedder.embed("padding");
+      db.upsertChunk(makeChunk({ id: "h1", content: "Use p-4 for padding." }), docId, emb);
+
+      // Warm the cache by searching v3
+      invalidateChunkCache();
+      await hybridSearch(db, embedder, {
+        query: "padding",
+        version: "v3",
+        limit: 5,
+      });
+
+      // Invalidate only v4 — v3 cache should remain
+      invalidateChunkCache("v4");
+
+      // v3 search should still work (cache intact or rebuilt)
+      const results = await hybridSearch(db, embedder, {
+        query: "padding",
+        version: "v3",
+        limit: 5,
+      });
+      expect(results.length).toBeGreaterThan(0);
+
+      db.close();
+    });
+  });
+
+  describe("searchFts error handling", () => {
+    it("returns empty array when FTS query fails", async () => {
+      const db = await createDatabase(testConfig());
+
+      // Close the DB to force FTS query to fail
+      db.close();
+
+      const results = db.searchFts("padding", "v3", 10);
+      expect(results).toHaveLength(0);
+    });
+  });
 });