@code-rag/core 0.1.0

package/dist/retrieval/cross-encoder-reranker.test.js

@@ -0,0 +1,305 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { CrossEncoderReRanker } from './cross-encoder-reranker.js';
+import { ReRankerError } from '../types/provider.js';
+// --- Helpers ---
+function makeSearchResult(overrides = {}) {
+    return {
+        chunkId: 'chunk-1',
+        content: 'function hello() {}',
+        nlSummary: 'A greeting function',
+        score: 0.95,
+        method: 'hybrid',
+        metadata: {
+            chunkType: 'function',
+            name: 'hello',
+            declarations: [],
+            imports: [],
+            exports: [],
+        },
+        chunk: {
+            id: 'chunk-1',
+            content: 'function hello() {}',
+            nlSummary: 'A greeting function',
+            filePath: 'src/utils/hello.ts',
+            startLine: 1,
+            endLine: 3,
+            language: 'typescript',
+            metadata: {
+                chunkType: 'function',
+                name: 'hello',
+                declarations: [],
+                imports: [],
+                exports: [],
+            },
+        },
+        ...overrides,
+    };
+}
+function createMockFetch(responses) {
+    let callIndex = 0;
+    return vi.fn().mockImplementation(() => {
+        const config = responses[callIndex++];
+        if (!config) {
+            return Promise.resolve({
+                ok: false,
+                status: 500,
+                json: () => Promise.resolve({}),
+            });
+        }
+        if (!config.ok) {
+            return Promise.resolve({
+                ok: false,
+                status: config.status ?? 500,
+                statusText: 'Internal Server Error',
+                json: () => Promise.resolve({}),
+            });
+        }
+        return Promise.resolve({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve({ response: config.response ?? '50' }),
+        });
+    });
+}
+// --- Tests ---
+describe('CrossEncoderReRanker', () => {
+    let reranker;
+    beforeEach(() => {
+        vi.restoreAllMocks();
+        reranker = new CrossEncoderReRanker({
+            model: 'qwen2.5-coder:7b',
+            topN: 3,
+        });
+    });
+    it('should return ok([]) for empty results array', async () => {
+        const result = await reranker.rerank('test query', []);
+        expect(result.isOk()).toBe(true);
+        expect(result._unsafeUnwrap()).toEqual([]);
+    });
+    it('should rerank results by Ollama-scored relevance', async () => {
+        const results = [
+            makeSearchResult({ chunkId: 'chunk-1', content: 'function a() {}' }),
+            makeSearchResult({ chunkId: 'chunk-2', content: 'function b() {}' }),
+            makeSearchResult({ chunkId: 'chunk-3', content: 'function c() {}' }),
+        ];
+        // Return different scores: chunk-1 gets 30, chunk-2 gets 90, chunk-3 gets 60
+        const mockFetch = createMockFetch([
+            { ok: true, response: '30' },
+            { ok: true, response: '90' },
+            { ok: true, response: '60' },
+        ]);
+        vi.stubGlobal('fetch', mockFetch);
+        const result = await reranker.rerank('find function', results);
+        expect(result.isOk()).toBe(true);
+        const reranked = result._unsafeUnwrap();
+        expect(reranked).toHaveLength(3);
+        // Sorted by score descending: chunk-2 (90), chunk-3 (60), chunk-1 (30)
+        expect(reranked[0].chunkId).toBe('chunk-2');
+        expect(reranked[1].chunkId).toBe('chunk-3');
+        expect(reranked[2].chunkId).toBe('chunk-1');
+    });
+    it('should only rerank topN results, remaining appended in original order', async () => {
+        const results = [
+            makeSearchResult({ chunkId: 'chunk-1', content: 'function a() {}' }),
+            makeSearchResult({ chunkId: 'chunk-2', content: 'function b() {}' }),
+            makeSearchResult({ chunkId: 'chunk-3', content: 'function c() {}' }),
+            makeSearchResult({ chunkId: 'chunk-4', content: 'function d() {}' }),
+            makeSearchResult({ chunkId: 'chunk-5', content: 'function e() {}' }),
+        ];
+        // topN is 3, so only first 3 are reranked
+        // chunk-1 gets 20, chunk-2 gets 80, chunk-3 gets 50
+        const mockFetch = createMockFetch([
+            { ok: true, response: '20' },
+            { ok: true, response: '80' },
+            { ok: true, response: '50' },
+        ]);
+        vi.stubGlobal('fetch', mockFetch);
+        const result = await reranker.rerank('find function', results);
+        expect(result.isOk()).toBe(true);
+        const reranked = result._unsafeUnwrap();
+        expect(reranked).toHaveLength(5);
+        // First 3 reranked by score: chunk-2 (80), chunk-3 (50), chunk-1 (20)
+        expect(reranked[0].chunkId).toBe('chunk-2');
+        expect(reranked[1].chunkId).toBe('chunk-3');
+        expect(reranked[2].chunkId).toBe('chunk-1');
+        // Remaining in original order
+        expect(reranked[3].chunkId).toBe('chunk-4');
+        expect(reranked[4].chunkId).toBe('chunk-5');
+        // Only 3 fetch calls should have been made
+        expect(mockFetch).toHaveBeenCalledTimes(3);
+    });
+    it('should handle non-numeric LLM response (defaults score to 50)', async () => {
+        const results = [
+            makeSearchResult({ chunkId: 'chunk-1', content: 'function a() {}' }),
+            makeSearchResult({ chunkId: 'chunk-2', content: 'function b() {}' }),
+        ];
+        const mockFetch = createMockFetch([
+            { ok: true, response: 'I cannot rate this code' },
+            { ok: true, response: '80' },
+        ]);
+        vi.stubGlobal('fetch', mockFetch);
+        const result = await reranker.rerank('find function', results);
+        expect(result.isOk()).toBe(true);
+        const reranked = result._unsafeUnwrap();
+        // chunk-2 (80) should come before chunk-1 (default 50)
+        expect(reranked[0].chunkId).toBe('chunk-2');
+        expect(reranked[1].chunkId).toBe('chunk-1');
+    });
+    it('should clamp scores to 0-100 (150 -> 100, -5 -> 0)', async () => {
+        const results = [
+            makeSearchResult({ chunkId: 'chunk-1', content: 'function a() {}' }),
+            makeSearchResult({ chunkId: 'chunk-2', content: 'function b() {}' }),
+            makeSearchResult({ chunkId: 'chunk-3', content: 'function c() {}' }),
+        ];
+        const mockFetch = createMockFetch([
+            { ok: true, response: '150' },
+            { ok: true, response: '-5' },
+            { ok: true, response: '50' },
+        ]);
+        vi.stubGlobal('fetch', mockFetch);
+        const result = await reranker.rerank('find function', results);
+        expect(result.isOk()).toBe(true);
+        const reranked = result._unsafeUnwrap();
+        // chunk-1 (150 clamped to 100), chunk-3 (50), chunk-2 (-5 clamped to 0)
+        expect(reranked[0].chunkId).toBe('chunk-1');
+        expect(reranked[1].chunkId).toBe('chunk-3');
+        expect(reranked[2].chunkId).toBe('chunk-2');
+    });
+    it('should gracefully handle transient fetch error on later results', async () => {
+        const rerankerWith5 = new CrossEncoderReRanker({
+            model: 'qwen2.5-coder:7b',
+            topN: 3,
+        });
+        const results = [
+            makeSearchResult({ chunkId: 'chunk-1', content: 'function a() {}' }),
+            makeSearchResult({ chunkId: 'chunk-2', content: 'function b() {}' }),
+            makeSearchResult({ chunkId: 'chunk-3', content: 'function c() {}' }),
+        ];
+        let callCount = 0;
+        const mockFetch = vi.fn().mockImplementation(() => {
+            callCount++;
+            if (callCount === 2) {
+                return Promise.reject(new TypeError('Connection reset'));
+            }
+            const score = callCount === 1 ? '90' : '30';
+            return Promise.resolve({
+                ok: true,
+                status: 200,
+                json: () => Promise.resolve({ response: score }),
+            });
+        });
+        vi.stubGlobal('fetch', mockFetch);
+        const result = await rerankerWith5.rerank('find function', results);
+        // Should succeed (not return err) since first call worked
+        expect(result.isOk()).toBe(true);
+        const reranked = result._unsafeUnwrap();
+        expect(reranked).toHaveLength(3);
+        // chunk-1 (90), chunk-2 (default 50 from transient error), chunk-3 (30)
+        expect(reranked[0].chunkId).toBe('chunk-1');
+        expect(reranked[1].chunkId).toBe('chunk-2');
+        expect(reranked[2].chunkId).toBe('chunk-3');
+    });
+    it('should handle Ollama HTTP error for individual result (assigns default score 50)', async () => {
+        const results = [
+            makeSearchResult({ chunkId: 'chunk-1', content: 'function a() {}' }),
+            makeSearchResult({ chunkId: 'chunk-2', content: 'function b() {}' }),
+            makeSearchResult({ chunkId: 'chunk-3', content: 'function c() {}' }),
+        ];
+        // Second request returns HTTP error
+        const mockFetch = createMockFetch([
+            { ok: true, response: '90' },
+            { ok: false, status: 500 },
+            { ok: true, response: '30' },
+        ]);
+        vi.stubGlobal('fetch', mockFetch);
+        const result = await reranker.rerank('find function', results);
+        expect(result.isOk()).toBe(true);
+        const reranked = result._unsafeUnwrap();
+        // chunk-1 (90), chunk-2 (default 50), chunk-3 (30)
+        expect(reranked[0].chunkId).toBe('chunk-1');
+        expect(reranked[1].chunkId).toBe('chunk-2');
+        expect(reranked[2].chunkId).toBe('chunk-3');
+    });
+    it('should return err(ReRankerError) when fetch throws (network error)', async () => {
+        const results = [
+            makeSearchResult({ chunkId: 'chunk-1', content: 'function a() {}' }),
+        ];
+        const mockFetch = vi.fn().mockRejectedValue(new TypeError('fetch failed'));
+        vi.stubGlobal('fetch', mockFetch);
+        const result = await reranker.rerank('find function', results);
+        expect(result.isErr()).toBe(true);
+        const error = result._unsafeUnwrapErr();
+        expect(error).toBeInstanceOf(ReRankerError);
+        expect(error.name).toBe('ReRankerError');
+        expect(error.message).toContain('fetch failed');
+    });
+    it('should send correct prompt format to Ollama', async () => {
+        const results = [
+            makeSearchResult({
+                chunkId: 'chunk-1',
+                content: 'function greet() { return "hi"; }',
+                metadata: {
+                    chunkType: 'function',
+                    name: 'greet',
+                    declarations: [],
+                    imports: [],
+                    exports: [],
+                },
+            }),
+        ];
+        const mockFetch = createMockFetch([{ ok: true, response: '75' }]);
+        vi.stubGlobal('fetch', mockFetch);
+        await reranker.rerank('greeting function', results);
+        expect(mockFetch).toHaveBeenCalledTimes(1);
+        const callArgs = mockFetch.mock.calls[0];
+        const body = JSON.parse(callArgs[1].body);
+        expect(body.prompt).toContain('Rate relevance 0-100');
+        expect(body.prompt).toContain('<query>greeting function</query>');
+        expect(body.prompt).toContain('<code type="function" name="greet">');
+        expect(body.prompt).toContain('function greet() { return "hi"; }');
+        expect(body.prompt).toContain('</code>');
+        expect(body.prompt).toContain('Score:');
+        expect(body.stream).toBe(false);
+    });
+    it('should use correct model from config', async () => {
+        const customReranker = new CrossEncoderReRanker({
+            model: 'custom-model:latest',
+            topN: 5,
+        });
+        const results = [makeSearchResult()];
+        const mockFetch = createMockFetch([{ ok: true, response: '75' }]);
+        vi.stubGlobal('fetch', mockFetch);
+        await customReranker.rerank('test', results);
+        const callArgs = mockFetch.mock.calls[0];
+        const body = JSON.parse(callArgs[1].body);
+        expect(body.model).toBe('custom-model:latest');
+    });
+    it('should respect timeout via AbortSignal', async () => {
+        const timeoutReranker = new CrossEncoderReRanker({
+            model: 'qwen2.5-coder:7b',
+            topN: 5,
+            timeout: 5000,
+        });
+        const results = [makeSearchResult()];
+        const mockFetch = createMockFetch([{ ok: true, response: '75' }]);
+        vi.stubGlobal('fetch', mockFetch);
+        await timeoutReranker.rerank('test', results);
+        const callArgs = mockFetch.mock.calls[0];
+        const options = callArgs[1];
+        expect(options.signal).toBeInstanceOf(AbortSignal);
+    });
+    it('should use correct base URL', async () => {
+        const customReranker = new CrossEncoderReRanker({
+            model: 'qwen2.5-coder:7b',
+            baseUrl: 'http://custom-host:8080',
+            topN: 5,
+        });
+        const results = [makeSearchResult()];
+        const mockFetch = createMockFetch([{ ok: true, response: '75' }]);
+        vi.stubGlobal('fetch', mockFetch);
+        await customReranker.rerank('test', results);
+        const callArgs = mockFetch.mock.calls[0];
+        expect(callArgs[0]).toBe('http://custom-host:8080/api/generate');
+    });
+});
+//# sourceMappingURL=cross-encoder-reranker.test.js.map

package/dist/retrieval/cross-encoder-reranker.test.js.map

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

package/dist/retrieval/index.d.ts

@@ -0,0 +1,8 @@
+export type { AnalyzedQuery, QueryIntent, QueryEntity } from './query-analyzer.js';
+export { QueryAnalyzer } from './query-analyzer.js';
+export type { ReadonlyGraph, RelationshipType, RelatedChunk, GraphExcerpt, ExpandedContext, } from './context-expander.js';
+export { ContextExpander } from './context-expander.js';
+export type { TokenBudgetConfig, AssembledContext, } from './token-budget.js';
+export { TokenBudgetOptimizer } from './token-budget.js';
+export type { CrossEncoderConfig } from './cross-encoder-reranker.js';
+export { CrossEncoderReRanker, ReRankerError } from './cross-encoder-reranker.js';

package/dist/retrieval/index.js

@@ -0,0 +1,4 @@
+export { QueryAnalyzer } from './query-analyzer.js';
+export { ContextExpander } from './context-expander.js';
+export { TokenBudgetOptimizer } from './token-budget.js';
+export { CrossEncoderReRanker, ReRankerError } from './cross-encoder-reranker.js';

package/dist/retrieval/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AASpD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAMxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAGzD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/retrieval/query-analyzer.d.ts

@@ -0,0 +1,29 @@
+import type { SearchFilters } from '../types/index.js';
+export type QueryIntent = 'find_definition' | 'find_usage' | 'understand_module' | 'find_similar' | 'general';
+export interface QueryEntity {
+    type: 'function' | 'class' | 'module' | 'file' | 'concept';
+    value: string;
+}
+export interface AnalyzedQuery {
+    originalQuery: string;
+    intent: QueryIntent;
+    entities: QueryEntity[];
+    suggestedFilters: SearchFilters;
+    expandedTerms: string[];
+}
+export declare class QueryAnalyzer {
+    /**
+     * Pattern-based query understanding. Analyzes a natural language query
+     * to detect intent, extract entities, suggest filters, and expand terms.
+     * This is a pure function (no LLM needed).
+     */
+    analyze(query: string): AnalyzedQuery;
+    /** Detect the user's intent based on pattern matching. */
+    private detectIntent;
+    /** Extract named entities (functions, classes, files, modules, concepts) from the query. */
+    private extractEntities;
+    /** Suggest search filters based on language/chunk type mentions in the query. */
+    private suggestFilters;
+    /** Expand query terms with related synonyms / domain terms. */
+    private expandTerms;
+}

package/dist/retrieval/query-analyzer.js

@@ -0,0 +1,238 @@
+const MAX_QUERY_LENGTH = 2000;
+/** Pattern-based definitions for intent detection. */
+const INTENT_PATTERNS = [
+    {
+        intent: 'find_definition',
+        patterns: [
+            /where\s+is\s+\S+\s+defined/i,
+            /definition\s+of/i,
+            /find\s+definition/i,
+            /define[ds]?\s/i,
+            /declaration\s+of/i,
+            /where\s+is\s+\S+\s+declared/i,
+            /show\s+(me\s+)?(the\s+)?definition/i,
+        ],
+    },
+    {
+        intent: 'find_usage',
+        patterns: [
+            /who\s+calls/i,
+            /usage\s+of/i,
+            /used\s+by/i,
+            /references?\s+to/i,
+            /callers?\s+of/i,
+            /where\s+is\s+\S+\s+used/i,
+            /find\s+usage/i,
+            /consumers?\s+of/i,
+        ],
+    },
+    {
+        intent: 'understand_module',
+        patterns: [
+            /how\s+does\s+\S+\s+work/i,
+            /explain\s/i,
+            /what\s+does\s+\S+\s+do/i,
+            /understand\s/i,
+            /overview\s+of/i,
+            /describe\s/i,
+            /how\s+is\s+\S+\s+implemented/i,
+        ],
+    },
+    {
+        intent: 'find_similar',
+        patterns: [
+            /similar\s+to/i,
+            /like\s+\S+/i,
+            /resembl/i,
+            /alternatives?\s+(to|for)/i,
+            /related\s+to/i,
+        ],
+    },
+];
+/** Well-known term expansion map. */
+const TERM_EXPANSIONS = new Map([
+    ['test', ['test', 'spec', 'describe', 'it', 'expect', 'assert']],
+    ['error', ['error', 'exception', 'throw', 'catch', 'fail']],
+    ['config', ['config', 'configuration', 'settings', 'options', 'preferences']],
+    ['auth', ['auth', 'authentication', 'authorization', 'login', 'session', 'token']],
+    ['api', ['api', 'endpoint', 'route', 'handler', 'controller']],
+    ['database', ['database', 'db', 'query', 'schema', 'migration', 'model']],
+    ['log', ['log', 'logger', 'logging', 'debug', 'trace']],
+    ['import', ['import', 'require', 'dependency', 'module']],
+    ['export', ['export', 'module', 'public']],
+    ['type', ['type', 'interface', 'typedef', 'schema']],
+    ['async', ['async', 'await', 'promise', 'callback']],
+    ['render', ['render', 'component', 'template', 'view']],
+]);
+/** Known language keywords for filter detection. */
+const LANGUAGE_KEYWORDS = new Map([
+    ['typescript', 'typescript'],
+    ['ts', 'typescript'],
+    ['javascript', 'javascript'],
+    ['js', 'javascript'],
+    ['python', 'python'],
+    ['py', 'python'],
+    ['rust', 'rust'],
+    ['go', 'go'],
+    ['java', 'java'],
+    ['c#', 'csharp'],
+    ['csharp', 'csharp'],
+]);
+/** Known chunk type keywords for filter detection. */
+const CHUNK_TYPE_KEYWORDS = new Map([
+    ['function', 'function'],
+    ['functions', 'function'],
+    ['method', 'method'],
+    ['methods', 'method'],
+    ['class', 'class'],
+    ['classes', 'class'],
+    ['interface', 'interface'],
+    ['interfaces', 'interface'],
+    ['type', 'type_alias'],
+    ['types', 'type_alias'],
+    ['module', 'module'],
+    ['modules', 'module'],
+]);
+/** Regex to detect PascalCase or camelCase identifiers (no /g — use findAll). */
+const IDENTIFIER_RE = /\b([A-Z][a-zA-Z0-9]*(?:[A-Z][a-z0-9]*)*|[a-z][a-zA-Z0-9]*(?:[A-Z][a-z0-9]*)+)\b/;
+/** Regex to detect file paths (no /g — use findAll). */
+const FILE_PATH_RE = /(?:[\w./-]+\/[\w.-]+\.[\w]+)/;
+/** Common English words that should not be extracted as entities. */
+const COMMON_WORDS = new Set([
+    'is', 'the', 'in', 'of', 'to', 'and', 'or', 'for', 'by',
+    'it', 'be', 'do', 'an', 'as', 'at', 'if', 'on', 'no',
+    'not', 'but', 'with', 'that', 'this', 'from', 'are', 'was',
+    'has', 'had', 'have', 'how', 'what', 'when', 'where', 'who',
+    'which', 'all', 'can', 'will', 'one', 'its', 'into', 'been',
+    'like', 'does', 'used', 'find', 'show', 'get', 'set',
+]);
+/** Safe matchAll that creates a fresh /g regex per call, avoiding stateful lastIndex. */
+function findAll(text, pattern) {
+    return [...text.matchAll(new RegExp(pattern.source, 'g'))].map((m) => m[0]);
+}
+export class QueryAnalyzer {
+    /**
+     * Pattern-based query understanding. Analyzes a natural language query
+     * to detect intent, extract entities, suggest filters, and expand terms.
+     * This is a pure function (no LLM needed).
+     */
+    analyze(query) {
+        const trimmed = query.trim();
+        if (trimmed.length === 0 || trimmed.length > MAX_QUERY_LENGTH) {
+            return {
+                originalQuery: query,
+                intent: 'general',
+                entities: [],
+                suggestedFilters: {},
+                expandedTerms: [],
+            };
+        }
+        const intent = this.detectIntent(trimmed);
+        const entities = this.extractEntities(trimmed);
+        const suggestedFilters = this.suggestFilters(trimmed);
+        const expandedTerms = this.expandTerms(trimmed);
+        return {
+            originalQuery: query,
+            intent,
+            entities,
+            suggestedFilters,
+            expandedTerms,
+        };
+    }
+    /** Detect the user's intent based on pattern matching. */
+    detectIntent(query) {
+        for (const { intent, patterns } of INTENT_PATTERNS) {
+            for (const pattern of patterns) {
+                if (pattern.test(query)) {
+                    return intent;
+                }
+            }
+        }
+        return 'general';
+    }
+    /** Extract named entities (functions, classes, files, modules, concepts) from the query. */
+    extractEntities(query) {
+        const entities = [];
+        const seen = new Set();
+        // Extract file paths
+        const filePaths = findAll(query, FILE_PATH_RE);
+        for (const fp of filePaths) {
+            if (!seen.has(fp)) {
+                seen.add(fp);
+                entities.push({ type: 'file', value: fp });
+            }
+        }
+        // Extract PascalCase / camelCase identifiers
+        const identifiers = findAll(query, IDENTIFIER_RE);
+        for (const id of identifiers) {
+            if (seen.has(id))
+                continue;
+            // Skip common English words that happen to match the regex
+            if (isCommonWord(id))
+                continue;
+            seen.add(id);
+            // PascalCase starting with uppercase = likely class
+            if (/^[A-Z]/.test(id)) {
+                entities.push({ type: 'class', value: id });
+            }
+            else {
+                // camelCase starting with lowercase = likely function
+                entities.push({ type: 'function', value: id });
+            }
+        }
+        return entities;
+    }
+    /** Suggest search filters based on language/chunk type mentions in the query. */
+    suggestFilters(query) {
+        const filters = {};
+        const lowerQuery = query.toLowerCase();
+        const words = lowerQuery.split(/\s+/);
+        // Detect language mentions
+        const languages = [];
+        for (const word of words) {
+            const lang = LANGUAGE_KEYWORDS.get(word);
+            if (lang && !languages.includes(lang)) {
+                languages.push(lang);
+            }
+        }
+        if (languages.length > 0) {
+            filters.languages = languages;
+        }
+        // Detect chunk type mentions
+        const chunkTypes = [];
+        for (const word of words) {
+            const ct = CHUNK_TYPE_KEYWORDS.get(word);
+            if (ct && !chunkTypes.includes(ct)) {
+                chunkTypes.push(ct);
+            }
+        }
+        if (chunkTypes.length > 0) {
+            filters.chunkTypes = chunkTypes;
+        }
+        // Detect file paths
+        const filePaths = findAll(query, FILE_PATH_RE);
+        if (filePaths.length > 0) {
+            filters.filePaths = [...new Set(filePaths)];
+        }
+        return filters;
+    }
+    /** Expand query terms with related synonyms / domain terms. */
+    expandTerms(query) {
+        const lowerQuery = query.toLowerCase();
+        const words = lowerQuery.split(/\s+/).filter((w) => w.length > 0);
+        const expanded = new Set(words);
+        for (const word of words) {
+            const expansions = TERM_EXPANSIONS.get(word);
+            if (expansions) {
+                for (const term of expansions) {
+                    expanded.add(term);
+                }
+            }
+        }
+        return [...expanded];
+    }
+}
+/** Check if a word is a common English word that should not be an entity. */
+function isCommonWord(word) {
+    return COMMON_WORDS.has(word.toLowerCase());
+}

package/dist/retrieval/query-analyzer.js.map

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

package/dist/retrieval/query-analyzer.test.d.ts

@@ -0,0 +1 @@
+export {};