@sfdxy/sf-documentation-knowledge 1.1.0 → 1.3.0

package/dist/tests/retrieval-quality.test.js

@@ -0,0 +1,161 @@
+/**
+ * Retrieval Quality Tests — validate that known-good queries
+ * return expected documents in the top results.
+ *
+ * These tests load the real graph.json and exercise the full
+ * search pipeline (stemming, trigram matching, TF-IDF scoring).
+ *
+ * Run: npm test
+ */
+import { describe, it, expect, beforeAll } from "vitest";
+import { GraphQuery, stem } from "../utils/graph-query.js";
+import { CodeIndex } from "../mcp/code-index.js";
+const KNOWLEDGE_DIR = "knowledge/current";
+// ─── Unit tests for the stemmer ─────────────────────────────────
+describe("stem()", () => {
+    it("strips -ing suffix", () => {
+        expect(stem("configuring")).toBe("configur");
+    });
+    it("strips -tion suffix", () => {
+        expect(stem("configuration")).toBe("configurat");
+    });
+    it("strips -ed suffix", () => {
+        expect(stem("queried")).toBe("query");
+    });
+    it("strips -es suffix", () => {
+        expect(stem("queries")).toBe("query");
+    });
+    it("strips -s suffix", () => {
+        expect(stem("objects")).toBe("object");
+    });
+    it("preserves short words", () => {
+        expect(stem("api")).toBe("api");
+        expect(stem("dml")).toBe("dml");
+    });
+    it("strips -ment suffix", () => {
+        expect(stem("deployment")).toBe("deploy");
+    });
+    it("strips -able suffix", () => {
+        expect(stem("batchable")).toBe("batch");
+    });
+});
+// ─── Integration tests: graph search retrieval quality ──────────
+describe("GraphQuery retrieval quality", () => {
+    let gq;
+    beforeAll(async () => {
+        gq = new GraphQuery(KNOWLEDGE_DIR);
+        await gq.load();
+    }, 60_000); // 60s timeout for loading 77MB graph
+    /**
+     * Test helper: asserts that at least one result's nodeId
+     * matches the provided pattern.
+     */
+    function expectResultMatching(results, pattern, query) {
+        const match = results.find((r) => pattern.test(r.nodeId));
+        expect(match, `Expected query "${query}" to return a result matching ${pattern}. Got: ${results.slice(0, 5).map((r) => r.nodeId).join(", ")}`).toBeDefined();
+    }
+    it("finds Batch Apex documentation", () => {
+        const results = gq.searchNodes("batch apex", { type: "document", limit: 10 });
+        expect(results.length).toBeGreaterThan(0);
+        expectResultMatching(results, /doc:apex-guide:.*batch/i, "batch apex");
+    });
+    it("finds SOQL documentation", () => {
+        const results = gq.searchNodes("SOQL queries", { type: "document", limit: 10 });
+        expect(results.length).toBeGreaterThan(0);
+        expectResultMatching(results, /doc:(soql-sosl|apex-guide):/, "SOQL queries");
+    });
+    it("finds REST API docs", () => {
+        const results = gq.searchNodes("REST API sobject describe", { type: "document", limit: 15, domain: "rest-api" });
+        expect(results.length).toBeGreaterThan(0);
+        // All results must be from rest-api since we pre-filter
+        for (const r of results) {
+            expect(r.nodeId).toMatch(/^doc:rest-api:/);
+        }
+    });
+    it("finds Platform Events docs", () => {
+        const results = gq.searchNodes("platform events publish", { type: "document", limit: 10 });
+        expect(results.length).toBeGreaterThan(0);
+        expectResultMatching(results, /doc:platform-events:/, "platform events publish");
+    });
+    it("domain pre-filter works", () => {
+        const results = gq.searchNodes("trigger", { type: "document", limit: 10, domain: "apex-guide" });
+        expect(results.length).toBeGreaterThan(0);
+        // All results must be in the apex-guide domain
+        for (const r of results) {
+            expect(r.nodeId).toMatch(/^doc:apex-guide:/);
+        }
+    });
+    it("finds LWC documentation", () => {
+        const results = gq.searchNodes("lightning web components", { type: "document", limit: 10 });
+        expect(results.length).toBeGreaterThan(0);
+        expectResultMatching(results, /doc:lwc:/, "lightning web components");
+    });
+    it("finds Metadata API docs", () => {
+        const results = gq.searchNodes("metadata api deploy", { type: "document", limit: 10 });
+        expect(results.length).toBeGreaterThan(0);
+        expectResultMatching(results, /doc:metadata-api:/, "metadata api deploy");
+    });
+    it("keyword search works", () => {
+        const results = gq.findDocsByKeyword("Apex", 10);
+        expect(results.length).toBeGreaterThan(0);
+    });
+    it("returns empty array for nonsense query", () => {
+        const results = gq.searchNodes("xyzzy_foobar_gibberish", { type: "document", limit: 5 });
+        expect(results.length).toBe(0);
+    });
+    it("stemming improves recall: 'configuring' matches 'configuration' docs", () => {
+        const stemmedResults = gq.searchNodes("configuring triggers", { type: "document", limit: 15 });
+        // Should find trigger-related docs even though query used "configuring" not exact match
+        expect(stemmedResults.length).toBeGreaterThan(0);
+    });
+    it("graph context returns valid doc context", () => {
+        // Find a real doc nodeId first
+        const results = gq.searchNodes("batch apex", { type: "document", limit: 1 });
+        expect(results.length).toBeGreaterThan(0);
+        const ctx = gq.getDocContext(results[0].nodeId);
+        expect(ctx).not.toBeNull();
+        expect(ctx.label).toBeTruthy();
+        expect(ctx.keywords).toBeInstanceOf(Array);
+    });
+    it("namespace listing returns Apex namespaces", () => {
+        const ns = gq.listNamespaces();
+        expect(ns.length).toBeGreaterThan(0);
+        const systemNs = ns.find((n) => n.namespace === "System");
+        expect(systemNs).toBeDefined();
+    });
+    it("domain listing returns 100+ domains", () => {
+        const domains = gq.listDomains();
+        expect(domains.length).toBeGreaterThanOrEqual(100);
+    });
+});
+// ─── CodeIndex retrieval quality ────────────────────────────────
+describe("CodeIndex retrieval quality", () => {
+    let codeIndex;
+    beforeAll(async () => {
+        codeIndex = new CodeIndex(KNOWLEDGE_DIR);
+        await codeIndex.load();
+    }, 120_000); // 2 min — reads all 33k files
+    it("finds Apex code examples", () => {
+        const snippets = codeIndex.search("batch apex", { limit: 5 });
+        expect(snippets.length).toBeGreaterThan(0);
+        expect(snippets[0].code.length).toBeGreaterThan(10);
+    });
+    it("language filter works", () => {
+        const snippets = codeIndex.search("query", { language: "soql", limit: 5 });
+        for (const s of snippets) {
+            expect(s.language).toBe("soql");
+        }
+    });
+    it("domain filter works", () => {
+        const snippets = codeIndex.search("apex", { domain: "apex-guide", limit: 5 });
+        for (const s of snippets) {
+            expect(s.domain).toBe("apex-guide");
+        }
+    });
+    it("returns stats with language breakdown", () => {
+        const stats = codeIndex.getStats();
+        expect(stats.totalSnippets).toBeGreaterThan(100);
+        expect(Object.keys(stats.languages).length).toBeGreaterThanOrEqual(2);
+    });
+});
+//# sourceMappingURL=retrieval-quality.test.js.map

package/dist/tests/retrieval-quality.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval-quality.test.js","sourceRoot":"","sources":["../../src/tests/retrieval-quality.test.ts"],"names":[],"mappings":"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"}

package/dist/utils/graph-query.d.ts

@@ -17,9 +17,26 @@ export interface DocContext {
     references: GraphSearchResult[];
     referencedBy: GraphSearchResult[];
 }
+export interface SearchOptions {
+    type?: string;
+    limit?: number;
+    /** Pre-filter by domain prefix (e.g. "apex-reference") */
+    domain?: string;
+    /** Pre-filter by docType */
+    docType?: string;
+}
+/** Simple, dependency-free stemmer optimised for technical documentation. */
+export declare function stem(word: string): string;
 /**
  * GraphQuery provides fast, in-memory traversal of the SF Knowledge Graph.
  * Load once, query many times.
+ *
+ * Indexing strategy (v2):
+ *   1. Stemmed label index — stem(word) → Set<nodeId>
+ *   2. Trigram index — 3-char substring → Set<stemmed word>  (for fuzzy recall)
+ *   3. Keyword index — keyword → Set<nodeId>  (from tagged_with edges)
+ *   4. IDF table — stem → log(N / df)  (for TF-IDF scoring)
+ *   5. LRU query cache — query key → results
  */
 export declare class GraphQuery {
     private graph;
@@ -27,8 +44,18 @@ export declare class GraphQuery {
     private graphPath;
     /** Inverted keyword index: lowercase keyword → Set of doc node IDs */
     private keywordIndex;
-    /** Inverted label index: lowercase word → Set of node IDs */
+    /** Stemmed label index: stemmed word → Set of node IDs */
     private labelIndex;
+    /** Trigram index: trigram → Set of stemmed words (for fuzzy matching) */
+    private trigramIndex;
+    /** IDF table: stemmed word → inverse-document-frequency weight */
+    private idfTable;
+    /** Total number of document nodes (for IDF calculation) */
+    private totalDocs;
+    /** LRU query cache: cache key → { results, timestamp } */
+    private queryCache;
+    private readonly CACHE_TTL_MS;
+    private readonly CACHE_MAX_SIZE;
     constructor(knowledgeDir?: string);
     /**
      * Load the graph into memory and build lookup indices.
@@ -36,14 +63,15 @@ export declare class GraphQuery {
     load(): Promise<void>;
     private ensureLoaded;
     private buildIndices;
+    private getCached;
+    private setCache;
     /**
      * Search across all node labels for a query string.
-     * Returns nodes whose labels contain the query terms.
+     *
+     * Uses stemming + trigram fuzzy matching + TF-IDF scoring.
+     * Supports optional pre-filters for domain and docType.
      */
-    searchNodes(query: string, options?: {
-        type?: string;
-        limit?: number;
-    }): GraphSearchResult[];
+    searchNodes(query: string, options?: SearchOptions): GraphSearchResult[];
     /**
      * Find documents tagged with a specific keyword.
      */

package/dist/utils/graph-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-query.d.ts","sourceRoot":"","sources":["../../src/utils/graph-query.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,YAAY,EAAE,iBAAiB,EAAE,CAAC;CACnC;AAED;;;GAGG;AACH,qBAAa,UAAU;IAErB,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAE1B,sEAAsE;IACtE,OAAO,CAAC,YAAY,CAAkC;IACtD,6DAA6D;IAC7D,OAAO,CAAC,UAAU,CAAkC;gBAExC,YAAY,SAAsB;IAI9C;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB3B,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,YAAY;IAgCpB;;;OAGG;IACH,WAAW,CACT,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAC9C,iBAAiB,EAAE;IAmDtB;;OAEG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,iBAAiB,EAAE;IAkBnE;;OAEG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,iBAAiB,EAAE;IAgD9D;;OAEG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,iBAAiB,EAAE;IAsBvD;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,EAAE;IAoBnD;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,iBAAiB,EAAE;IAsB/D;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAiEnD;;OAEG;IACH,WAAW,IAAI,iBAAiB,EAAE;IAiBlC;;OAEG;IACH,cAAc,IAAI,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAiBhE;;OAEG;IACH,YAAY,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAiB/D,6BAA6B;IAC7B,QAAQ,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;CAI7C"}
+{"version":3,"file":"graph-query.d.ts","sourceRoot":"","sources":["../../src/utils/graph-query.ts"],"names":[],"mappings":"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"}

package/dist/utils/graph-query.js

@@ -6,9 +6,81 @@ import pkg from "graphology";
 const DirectedGraph = pkg.DirectedGraph || pkg;
 import { createChildLogger } from "./logger.js";
 const log = createChildLogger("utils:graph-query");
+// ─── Lightweight suffix-stripping stemmer ─────────────────────────
+const SUFFIX_RULES = [
+    [/ational$/, "ate"],
+    [/tional$/, "tion"],
+    [/ization$/, "ize"],
+    [/fulness$/, "ful"],
+    [/ousness$/, "ous"],
+    [/iveness$/, "ive"],
+    [/ibilities$/, "ible"],
+    [/ically$/, "ic"],
+    [/ating$/, "ate"],
+    [/ising$/, "ise"],
+    [/izing$/, "ize"],
+    [/abling$/, "able"],
+    [/ement$/, ""],
+    [/ment$/, ""],
+    [/tion$/, "t"],
+    [/sion$/, "s"],
+    [/ness$/, ""],
+    [/able$/, ""],
+    [/ible$/, ""],
+    [/ment$/, ""],
+    [/ious$/, ""],
+    [/eous$/, ""],
+    [/ous$/, ""],
+    [/ive$/, ""],
+    [/ful$/, ""],
+    [/ing$/, ""],
+    [/ies$/, "y"],
+    [/ied$/, "y"],
+    [/ion$/, ""],
+    [/ers$/, ""],
+    [/est$/, ""],
+    [/ely$/, ""],
+    [/ed$/, ""],
+    [/er$/, ""],
+    [/ly$/, ""],
+    [/es$/, ""],
+    [/s$/, ""],
+];
+/** Simple, dependency-free stemmer optimised for technical documentation. */
+export function stem(word) {
+    if (word.length < 4)
+        return word;
+    const lower = word.toLowerCase();
+    for (const [re, replacement] of SUFFIX_RULES) {
+        if (re.test(lower)) {
+            const stemmed = lower.replace(re, replacement);
+            // Only keep stems ≥ 3 chars to avoid over-stripping
+            if (stemmed.length >= 3)
+                return stemmed;
+        }
+    }
+    return lower;
+}
+// ─── Trigram helpers ──────────────────────────────────────────────
+function trigrams(word) {
+    if (word.length < 3)
+        return [word];
+    const tris = [];
+    for (let i = 0; i <= word.length - 3; i++) {
+        tris.push(word.slice(i, i + 3));
+    }
+    return tris;
+}
 /**
  * GraphQuery provides fast, in-memory traversal of the SF Knowledge Graph.
  * Load once, query many times.
+ *
+ * Indexing strategy (v2):
+ *   1. Stemmed label index — stem(word) → Set<nodeId>
+ *   2. Trigram index — 3-char substring → Set<stemmed word>  (for fuzzy recall)
+ *   3. Keyword index — keyword → Set<nodeId>  (from tagged_with edges)
+ *   4. IDF table — stem → log(N / df)  (for TF-IDF scoring)
+ *   5. LRU query cache — query key → results
  */
 export class GraphQuery {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -17,8 +89,18 @@ export class GraphQuery {
     graphPath;
     /** Inverted keyword index: lowercase keyword → Set of doc node IDs */
     keywordIndex = new Map();
-    /** Inverted label index: lowercase word → Set of node IDs */
+    /** Stemmed label index: stemmed word → Set of node IDs */
     labelIndex = new Map();
+    /** Trigram index: trigram → Set of stemmed words (for fuzzy matching) */
+    trigramIndex = new Map();
+    /** IDF table: stemmed word → inverse-document-frequency weight */
+    idfTable = new Map();
+    /** Total number of document nodes (for IDF calculation) */
+    totalDocs = 0;
+    /** LRU query cache: cache key → { results, timestamp } */
+    queryCache = new Map();
+    CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+    CACHE_MAX_SIZE = 200;
     constructor(knowledgeDir = "knowledge/current") {
         this.graphPath = path.join(knowledgeDir, "graph.json");
     }
@@ -42,7 +124,8 @@ export class GraphQuery {
             throw new Error("Graph not loaded. Call load() first.");
     }
     buildIndices() {
-        // Build keyword → docs index
+        // Build keyword → docs index from tagged_with edges
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.graph.forEachEdge((_, attrs, source, target) => {
             if (attrs.type === "tagged_with") {
                 const targetAttrs = this.graph.getNodeAttributes(target);
@@ -55,62 +138,164 @@ export class GraphQuery {
                 }
             }
         });
-        // Build label word → node index
+        // Build stemmed label index + trigram index + IDF table
+        // Track document frequency (how many DOCUMENT nodes each stem appears in)
+        const docFrequency = new Map();
+        let docCount = 0;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.graph.forEachNode((nodeId, attrs) => {
             const label = attrs.label?.toLowerCase();
             if (!label)
                 return;
-            const words = label.split(/\s+/);
+            const isDoc = attrs.type === "document";
+            if (isDoc)
+                docCount++;
+            const words = label.split(/[\s_\-.]+/);
+            const seenStems = new Set();
             for (const word of words) {
                 if (word.length < 3)
                     continue;
-                if (!this.labelIndex.has(word)) {
-                    this.labelIndex.set(word, new Set());
+                const stemmed = stem(word);
+                seenStems.add(stemmed);
+                // Stemmed label index
+                if (!this.labelIndex.has(stemmed)) {
+                    this.labelIndex.set(stemmed, new Set());
+                }
+                this.labelIndex.get(stemmed).add(nodeId);
+                // Trigram index: map each trigram to the stemmed word
+                for (const tri of trigrams(stemmed)) {
+                    if (!this.trigramIndex.has(tri)) {
+                        this.trigramIndex.set(tri, new Set());
+                    }
+                    this.trigramIndex.get(tri).add(stemmed);
+                }
+            }
+            // Track DF for document nodes only
+            if (isDoc) {
+                for (const s of seenStems) {
+                    docFrequency.set(s, (docFrequency.get(s) || 0) + 1);
                 }
-                this.labelIndex.get(word).add(nodeId);
             }
         });
+        // Compute IDF: log(N / df) for each stem
+        this.totalDocs = docCount;
+        for (const [stemmedWord, df] of docFrequency) {
+            this.idfTable.set(stemmedWord, Math.log(docCount / df));
+        }
+        log.info({
+            labelTerms: this.labelIndex.size,
+            trigrams: this.trigramIndex.size,
+            keywords: this.keywordIndex.size,
+            docs: docCount,
+        }, "Search indices built (stemmed + trigram + IDF)");
+    }
+    // ─── Cache helpers ──────────────────────────────────────────────
+    getCached(key) {
+        const entry = this.queryCache.get(key);
+        if (!entry)
+            return null;
+        if (Date.now() - entry.ts > this.CACHE_TTL_MS) {
+            this.queryCache.delete(key);
+            return null;
+        }
+        return entry.results;
+    }
+    setCache(key, results) {
+        // Evict oldest if at capacity
+        if (this.queryCache.size >= this.CACHE_MAX_SIZE) {
+            const oldest = this.queryCache.keys().next().value;
+            if (oldest !== undefined)
+                this.queryCache.delete(oldest);
+        }
+        this.queryCache.set(key, { results, ts: Date.now() });
     }
     // ─── Query Methods ─────────────────────────────────────────────
     /**
      * Search across all node labels for a query string.
-     * Returns nodes whose labels contain the query terms.
+     *
+     * Uses stemming + trigram fuzzy matching + TF-IDF scoring.
+     * Supports optional pre-filters for domain and docType.
      */
     searchNodes(query, options = {}) {
         this.ensureLoaded();
-        const { type, limit = 25 } = options;
-        const terms = query.toLowerCase().split(/\s+/).filter((t) => t.length >= 3);
-        if (terms.length === 0)
+        const { type, limit = 25, domain, docType } = options;
+        // Check cache
+        const cacheKey = `search:${query}|${type || ""}|${domain || ""}|${docType || ""}|${limit}`;
+        const cached = this.getCached(cacheKey);
+        if (cached)
+            return cached;
+        // Tokenise and stem the query
+        const rawTerms = query.toLowerCase()
+            .replace(/[._]/g, " ")
+            .replace(/([a-z])([A-Z])/g, "$1 $2")
+            .split(/\s+/)
+            .filter((t) => t.length >= 3);
+        if (rawTerms.length === 0)
             return [];
-        // Find candidate nodes from label index
+        const stemmedTerms = rawTerms.map(stem);
+        // Collect candidate nodes via stemmed label index
+        // For each stemmed term, find exact stem matches + trigram-expanded fuzzy matches
         const candidates = new Map();
-        for (const term of terms) {
-            for (const [word, nodeIds] of this.labelIndex) {
-                // Require meaningful overlap: shorter string must be ≥60% of longer
-                const shorter = Math.min(word.length, term.length);
-                const longer = Math.max(word.length, term.length);
-                if (shorter / longer < 0.6)
-                    continue;
-                if (word.includes(term) || term.includes(word)) {
-                    for (const nodeId of nodeIds) {
-                        candidates.set(nodeId, (candidates.get(nodeId) || 0) + 1);
+        for (const st of stemmedTerms) {
+            const matchedStems = new Set();
+            // Exact stem match
+            if (this.labelIndex.has(st)) {
+                matchedStems.add(st);
+            }
+            // Trigram fuzzy expansion: find other stems that share trigrams
+            const queryTrigrams = trigrams(st);
+            const trigramHits = new Map();
+            for (const tri of queryTrigrams) {
+                const stems = this.trigramIndex.get(tri);
+                if (stems) {
+                    for (const s of stems) {
+                        trigramHits.set(s, (trigramHits.get(s) || 0) + 1);
                     }
                 }
             }
+            // Accept stems with ≥60% trigram overlap
+            const threshold = Math.max(1, Math.floor(queryTrigrams.length * 0.6));
+            for (const [s, count] of trigramHits) {
+                if (count >= threshold)
+                    matchedStems.add(s);
+            }
+            // Collect node IDs from matched stems
+            for (const ms of matchedStems) {
+                const nodeIds = this.labelIndex.get(ms);
+                if (!nodeIds)
+                    continue;
+                // Weight by IDF of the matched stem
+                const idf = this.idfTable.get(ms) || 1.0;
+                for (const nodeId of nodeIds) {
+                    candidates.set(nodeId, (candidates.get(nodeId) || 0) + idf);
+                }
+            }
         }
-        // Score and filter
+        // Score, filter, and rank
         const results = [];
-        for (const [nodeId, matchCount] of candidates) {
+        const queryLower = query.toLowerCase();
+        for (const [nodeId, tfidfScore] of candidates) {
             const attrs = this.graph.getNodeAttributes(nodeId);
+            // Pre-filter by type
             if (type && attrs.type !== type)
                 continue;
+            // Pre-filter by domain (node IDs are doc:<domain>:<topic>)
+            if (domain && !nodeId.startsWith(`doc:${domain}:`))
+                continue;
+            // Pre-filter by docType
+            if (docType && attrs.docType !== docType)
+                continue;
             const label = attrs.label?.toLowerCase() || "";
-            // Exact match gets highest score
-            let score = matchCount / terms.length;
-            if (label === query.toLowerCase())
-                score = 10;
-            else if (label.startsWith(query.toLowerCase()))
-                score += 2;
+            // Compute final score: TF-IDF base + bonuses
+            let score = tfidfScore / stemmedTerms.length; // normalize by query length
+            // Exact match bonus
+            if (label === queryLower)
+                score += 10;
+            else if (label.startsWith(queryLower))
+                score += 3;
+            // Contains full query bonus
+            else if (label.includes(queryLower))
+                score += 1.5;
             results.push({
                 nodeId,
                 type: attrs.type,
@@ -120,10 +305,12 @@ export class GraphQuery {
                 score,
             });
         }
-        return results
-            .filter((r) => (r.score || 0) >= 0.3) // Filter weak matches
+        const sorted = results
+            .filter((r) => (r.score || 0) >= 0.3)
             .sort((a, b) => (b.score || 0) - (a.score || 0))
             .slice(0, limit);
+        this.setCache(cacheKey, sorted);
+        return sorted;
     }
     /**
      * Find documents tagged with a specific keyword.
@@ -159,6 +346,7 @@ export class GraphQuery {
             const nextFrontier = [];
             for (const nodeId of frontier) {
                 // Outgoing reference edges
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 this.graph.forEachOutEdge(nodeId, (_, attrs, _src, target) => {
                     if (attrs.type === "references" && !visited.has(target)) {
                         visited.add(target);
@@ -174,6 +362,7 @@ export class GraphQuery {
                     }
                 });
                 // Incoming reference edges
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 this.graph.forEachInEdge(nodeId, (_, attrs, source) => {
                     if (attrs.type === "references" && !visited.has(source)) {
                         visited.add(source);
@@ -202,6 +391,7 @@ export class GraphQuery {
         if (!this.graph.hasNode(nsNodeId))
             return [];
         const results = [];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.graph.forEachInEdge(nsNodeId, (_, attrs, source) => {
             if (attrs.type === "belongs_to_namespace") {
                 const sourceAttrs = this.graph.getNodeAttributes(source);
@@ -225,6 +415,7 @@ export class GraphQuery {
         if (!this.graph.hasNode(serviceNodeId))
             return [];
         const results = [];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.graph.forEachInEdge(serviceNodeId, (_, attrs, source) => {
             if (attrs.type === "belongs_to_service") {
                 const sourceAttrs = this.graph.getNodeAttributes(source);
@@ -246,6 +437,7 @@ export class GraphQuery {
         if (!this.graph.hasNode(dtNodeId))
             return [];
         const results = [];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.graph.forEachInEdge(dtNodeId, (_, attrs, source) => {
             if (attrs.type === "is_type" && results.length < limit) {
                 const sourceAttrs = this.graph.getNodeAttributes(source);
@@ -274,6 +466,7 @@ export class GraphQuery {
         const references = [];
         const referencedBy = [];
         // Traverse outgoing edges
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.graph.forEachOutEdge(docNodeId, (_, edgeAttrs, _src, target) => {
             const targetAttrs = this.graph.getNodeAttributes(target);
             switch (edgeAttrs.type) {
@@ -295,6 +488,7 @@ export class GraphQuery {
             }
         });
         // Traverse incoming edges
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.graph.forEachInEdge(docNodeId, (_, edgeAttrs, source) => {
             const sourceAttrs = this.graph.getNodeAttributes(source);
             switch (edgeAttrs.type) {
@@ -330,6 +524,7 @@ export class GraphQuery {
     listDomains() {
         this.ensureLoaded();
         const results = [];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.graph.forEachNode((nodeId, attrs) => {
             if (attrs.type === "domain") {
                 results.push({
@@ -347,9 +542,11 @@ export class GraphQuery {
     listNamespaces() {
         this.ensureLoaded();
         const results = [];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.graph.forEachNode((nodeId, attrs) => {
             if (attrs.type === "namespace") {
                 let docCount = 0;
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 this.graph.forEachInEdge(nodeId, (_, edgeAttrs) => {
                     if (edgeAttrs.type === "belongs_to_namespace")
                         docCount++;
@@ -365,9 +562,11 @@ export class GraphQuery {
     listServices() {
         this.ensureLoaded();
         const results = [];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.graph.forEachNode((nodeId, attrs) => {
             if (attrs.type === "service") {
                 let domainCount = 0;
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 this.graph.forEachInEdge(nodeId, (_, edgeAttrs) => {
                     if (edgeAttrs.type === "belongs_to_service")
                         domainCount++;