@renseiai/agentfactory-code-intelligence 0.8.8 → 0.8.9

package/dist/src/search/__tests__/query-classifier.test.js

@@ -0,0 +1,136 @@
+import { describe, it, expect } from 'vitest';
+import { classifyQuery } from '../query-classifier.js';
+describe('classifyQuery', () => {
+    // ── Identifier detection ──────────────────────────────────────────
+    describe('camelCase detection', () => {
+        it('classifies camelCase as identifier', () => {
+            const result = classifyQuery('handleRequest');
+            expect(result.type).toBe('identifier');
+            expect(result.alpha).toBe(0.25);
+        });
+        it('classifies multi-word camelCase as identifier', () => {
+            const result = classifyQuery('getUserById');
+            expect(result.type).toBe('identifier');
+            expect(result.alpha).toBe(0.25);
+        });
+    });
+    describe('snake_case detection', () => {
+        it('classifies snake_case as identifier', () => {
+            const result = classifyQuery('get_user_by_id');
+            expect(result.type).toBe('identifier');
+            expect(result.alpha).toBe(0.25);
+        });
+        it('classifies double snake_case as identifier', () => {
+            const result = classifyQuery('handle_http_request');
+            expect(result.type).toBe('identifier');
+            expect(result.alpha).toBe(0.25);
+        });
+    });
+    describe('PascalCase detection', () => {
+        it('classifies PascalCase as identifier', () => {
+            const result = classifyQuery('UserService');
+            expect(result.type).toBe('identifier');
+            expect(result.alpha).toBe(0.25);
+        });
+        it('classifies multi-word PascalCase as identifier', () => {
+            const result = classifyQuery('HttpRequestHandler');
+            expect(result.type).toBe('identifier');
+            expect(result.alpha).toBe(0.25);
+        });
+    });
+    describe('CONSTANT_CASE detection', () => {
+        it('classifies CONSTANT_CASE as identifier', () => {
+            const result = classifyQuery('MAX_RETRIES');
+            expect(result.type).toBe('identifier');
+            expect(result.alpha).toBe(0.25);
+        });
+        it('classifies single CONSTANT as identifier', () => {
+            const result = classifyQuery('HTTP_TIMEOUT');
+            expect(result.type).toBe('identifier');
+            expect(result.alpha).toBe(0.25);
+        });
+    });
+    describe('dot.notation detection', () => {
+        it('classifies dot notation as identifier', () => {
+            const result = classifyQuery('req.body');
+            expect(result.type).toBe('identifier');
+            expect(result.alpha).toBe(0.25);
+        });
+        it('classifies chained dot notation as identifier', () => {
+            const result = classifyQuery('this.service.getUser');
+            expect(result.type).toBe('identifier');
+            expect(result.alpha).toBe(0.25);
+        });
+    });
+    describe('operator tokens', () => {
+        it('classifies :: operator token as identifier', () => {
+            const result = classifyQuery('std::vector');
+            expect(result.type).toBe('identifier');
+            expect(result.alpha).toBe(0.25);
+        });
+        it('classifies -> operator token as identifier', () => {
+            const result = classifyQuery('node->next');
+            expect(result.type).toBe('identifier');
+            expect(result.alpha).toBe(0.25);
+        });
+    });
+    // ── Natural language detection ────────────────────────────────────
+    describe('natural language queries', () => {
+        it('classifies plain English as natural', () => {
+            const result = classifyQuery('how to handle errors');
+            expect(result.type).toBe('natural');
+            expect(result.alpha).toBe(0.75);
+        });
+        it('classifies question-style query as natural', () => {
+            const result = classifyQuery('authentication middleware for express');
+            expect(result.type).toBe('natural');
+            expect(result.alpha).toBe(0.75);
+        });
+        it('classifies descriptive query as natural', () => {
+            const result = classifyQuery('database connection pooling strategy');
+            expect(result.type).toBe('natural');
+            expect(result.alpha).toBe(0.75);
+        });
+        it('classifies short natural query as natural', () => {
+            const result = classifyQuery('error handling');
+            expect(result.type).toBe('natural');
+            expect(result.alpha).toBe(0.75);
+        });
+    });
+    // ── Mixed queries ─────────────────────────────────────────────────
+    describe('mixed queries', () => {
+        it('classifies query with one identifier in natural context as mixed', () => {
+            const result = classifyQuery('fix handleRequest error');
+            expect(result.type).toBe('mixed');
+            expect(result.alpha).toBe(0.55);
+        });
+        it('classifies query with identifier and natural words as mixed', () => {
+            const result = classifyQuery('where is UserService defined');
+            expect(result.type).toBe('mixed');
+            expect(result.alpha).toBe(0.55);
+        });
+        it('classifies query mixing snake_case with natural as mixed', () => {
+            const result = classifyQuery('update get_user_by_id function');
+            expect(result.type).toBe('mixed');
+            expect(result.alpha).toBe(0.55);
+        });
+    });
+    // ── Edge cases ────────────────────────────────────────────────────
+    describe('edge cases', () => {
+        it('handles empty query', () => {
+            const result = classifyQuery('');
+            expect(result.type).toBe('natural');
+            expect(result.alpha).toBe(0.75);
+        });
+        it('handles single word that is not an identifier', () => {
+            const result = classifyQuery('search');
+            expect(result.type).toBe('natural');
+            expect(result.alpha).toBe(0.75);
+        });
+        it('handles multiple identifiers', () => {
+            const result = classifyQuery('handleRequest processData getUserById');
+            expect(result.type).toBe('identifier');
+            expect(result.alpha).toBe(0.25);
+        });
+    });
+});

package/dist/src/search/hybrid-search.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Hybrid search engine combining BM25 lexical search with dense vector semantic search.
+ * Uses Convex Combination Score (CCS) fusion with query-adaptive alpha weighting
+ * and Reciprocal Rank Fusion (RRF) as a fallback.
+ */
+import type { SearchQuery, SearchResult } from '../types.js';
+import type { VectorStore } from '../vector/vector-store.js';
+import type { EmbeddingProvider } from '../embedding/embedding-provider.js';
+import type { SearchEngine } from './search-engine.js';
+import type { RerankerConfig } from '../reranking/reranker-provider.js';
+export interface HybridSearchConfig {
+    /** Weight for vector scores in CCS (0 = BM25-only, 1 = vector-only). Default: 0.45 */
+    alpha: number;
+    /** Enable query-adaptive alpha selection. Default: true */
+    adaptiveAlpha: boolean;
+    /** Number of BM25 candidates to retrieve. Default: 100 */
+    bm25TopK: number;
+    /** Number of vector candidates to retrieve. Default: 100 */
+    vectorTopK: number;
+    /** Fusion method. Default: 'ccs' */
+    fusionMethod: 'ccs' | 'rrf';
+    /** RRF constant k. Default: 60 */
+    rrfK: number;
+}
+export declare class HybridSearchEngine {
+    private bm25Engine;
+    private vectorStore;
+    private embeddingProvider;
+    private config;
+    private rerankerConfig;
+    constructor(bm25Engine: SearchEngine, vectorStore: VectorStore | null, embeddingProvider: EmbeddingProvider | null, config?: Partial<HybridSearchConfig>, rerankerConfig?: RerankerConfig | null);
+    /** Run hybrid search combining BM25 and vector retrieval. */
+    search(query: SearchQuery): Promise<SearchResult[]>;
+    private hybridFusion;
+    /**
+     * Convex Combination Score fusion.
+     * score(d) = alpha * normalized_vector(d) + (1 - alpha) * normalized_bm25(d)
+     */
+    private ccsFusion;
+    /**
+     * Reciprocal Rank Fusion.
+     * rrf_score(d) = sum(1 / (k + rank_i(d))) for each ranking
+     */
+    private rrfFusion;
+    /**
+     * Apply cross-encoder reranking to search results.
+     * Returns results unchanged if reranker is not configured, disabled, or errors.
+     */
+    private applyReranking;
+    /** Build text for reranking from a search result's symbol metadata. */
+    private buildRerankText;
+    /** Create a document key for matching BM25 results to vector results. */
+    private makeDocKey;
+    private matchPattern;
+}
+//# sourceMappingURL=hybrid-search.d.ts.map

package/dist/src/search/hybrid-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-search.d.ts","sourceRoot":"","sources":["../../../src/search/hybrid-search.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAA;AAC3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,mCAAmC,CAAA;AAMvF,MAAM,WAAW,kBAAkB;IACjC,sFAAsF;IACtF,KAAK,EAAE,MAAM,CAAA;IACb,2DAA2D;IAC3D,aAAa,EAAE,OAAO,CAAA;IACtB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAA;IAClB,oCAAoC;IACpC,YAAY,EAAE,KAAK,GAAG,KAAK,CAAA;IAC3B,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;CACb;AA0BD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,UAAU,CAAc;IAChC,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,iBAAiB,CAA0B;IACnD,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,cAAc,CAAuB;gBAG3C,UAAU,EAAE,YAAY,EACxB,WAAW,EAAE,WAAW,GAAG,IAAI,EAC/B,iBAAiB,EAAE,iBAAiB,GAAG,IAAI,EAC3C,MAAM,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,EACpC,cAAc,CAAC,EAAE,cAAc,GAAG,IAAI;IASxC,6DAA6D;IACvD,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;YA2B3C,YAAY;IA6F1B;;;OAGG;IACH,OAAO,CAAC,SAAS;IAuEjB;;;OAGG;IACH,OAAO,CAAC,SAAS;IA2BjB;;;OAGG;YACW,cAAc;IAkD5B,uEAAuE;IACvE,OAAO,CAAC,eAAe;IAmBvB,yEAAyE;IACzE,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,YAAY;CAarB"}

package/dist/src/search/hybrid-search.js

@@ -0,0 +1,299 @@
+/**
+ * Hybrid search engine combining BM25 lexical search with dense vector semantic search.
+ * Uses Convex Combination Score (CCS) fusion with query-adaptive alpha weighting
+ * and Reciprocal Rank Fusion (RRF) as a fallback.
+ */
+import { minMaxNormalize } from './score-normalizer.js';
+import { classifyQuery } from './query-classifier.js';
+const DEFAULT_CONFIG = {
+    alpha: 0.45,
+    adaptiveAlpha: true,
+    bm25TopK: 100,
+    vectorTopK: 100,
+    fusionMethod: 'ccs',
+    rrfK: 60,
+};
+// ── Hybrid Search Engine ─────────────────────────────────────────────
+export class HybridSearchEngine {
+    bm25Engine;
+    vectorStore;
+    embeddingProvider;
+    config;
+    rerankerConfig;
+    constructor(bm25Engine, vectorStore, embeddingProvider, config, rerankerConfig) {
+        this.bm25Engine = bm25Engine;
+        this.vectorStore = vectorStore;
+        this.embeddingProvider = embeddingProvider;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.rerankerConfig = rerankerConfig ?? null;
+    }
+    /** Run hybrid search combining BM25 and vector retrieval. */
+    async search(query) {
+        // Step 1: Get BM25 results (always available)
+        const bm25Query = {
+            ...query,
+            maxResults: this.config.bm25TopK,
+        };
+        const bm25Results = this.bm25Engine.search(bm25Query);
+        let results;
+        // Step 2: If vector store and embedding provider are available, do hybrid fusion
+        if (this.vectorStore && this.embeddingProvider && this.vectorStore.size() > 0) {
+            results = await this.hybridFusion(query, bm25Results);
+        }
+        else {
+            // Step 3: Fallback to BM25-only
+            results = bm25Results;
+            if (query.maxResults) {
+                results = results.slice(0, query.maxResults);
+            }
+        }
+        // Step 4: Apply reranking if configured and enabled
+        results = await this.applyReranking(query.query, results);
+        return results;
+    }
+    async hybridFusion(query, bm25Results) {
+        // Embed the query
+        const queryVector = await this.embeddingProvider.embedQuery(query.query);
+        // Search vector store
+        const vectorResults = await this.vectorStore.search(queryVector, this.config.vectorTopK);
+        // Build candidate map keyed by docKey
+        const candidates = new Map();
+        // Add BM25 results
+        for (let i = 0; i < bm25Results.length; i++) {
+            const r = bm25Results[i];
+            const key = this.makeDocKey(r.symbol.filePath, r.symbol.name, r.symbol.line);
+            candidates.set(key, {
+                bm25Score: r.score,
+                vectorScore: undefined,
+                bm25Rank: i + 1,
+                vectorRank: undefined,
+                result: r,
+            });
+        }
+        // Add/merge vector results
+        for (let i = 0; i < vectorResults.length; i++) {
+            const vr = vectorResults[i];
+            const meta = vr.chunk.metadata;
+            const key = this.makeDocKey(meta.filePath, meta.symbolName ?? '', meta.startLine);
+            const existing = candidates.get(key);
+            if (existing) {
+                existing.vectorScore = vr.score;
+                existing.vectorRank = i + 1;
+            }
+            else {
+                // Vector-only result — create a SearchResult from the chunk metadata
+                candidates.set(key, {
+                    bm25Score: undefined,
+                    vectorScore: vr.score,
+                    bm25Rank: undefined,
+                    vectorRank: i + 1,
+                    result: {
+                        symbol: {
+                            name: meta.symbolName ?? '',
+                            kind: meta.symbolKind ?? 'function',
+                            filePath: meta.filePath,
+                            line: meta.startLine,
+                            endLine: meta.endLine,
+                            language: meta.language,
+                            exported: false,
+                        },
+                        score: 0, // Will be set by fusion
+                        matchType: 'semantic',
+                    },
+                });
+            }
+        }
+        // Determine alpha
+        const alpha = this.config.adaptiveAlpha
+            ? classifyQuery(query.query).alpha
+            : this.config.alpha;
+        // Fuse scores
+        const fused = this.config.fusionMethod === 'ccs'
+            ? this.ccsFusion(candidates, alpha)
+            : this.rrfFusion(candidates);
+        // Apply filters
+        let results = fused.filter(r => {
+            if (query.symbolKinds && !query.symbolKinds.includes(r.symbol.kind))
+                return false;
+            if (query.language && r.symbol.language !== query.language)
+                return false;
+            if (query.filePattern && !this.matchPattern(r.symbol.filePath, query.filePattern))
+                return false;
+            return true;
+        });
+        // Sort by fused score descending
+        results.sort((a, b) => b.score - a.score);
+        // Limit results
+        if (query.maxResults) {
+            results = results.slice(0, query.maxResults);
+        }
+        return results;
+    }
+    /**
+     * Convex Combination Score fusion.
+     * score(d) = alpha * normalized_vector(d) + (1 - alpha) * normalized_bm25(d)
+     */
+    ccsFusion(candidates, alpha) {
+        // Collect raw scores for normalization
+        const bm25Scores = [];
+        const vectorScores = [];
+        for (const c of candidates.values()) {
+            if (c.bm25Score !== undefined)
+                bm25Scores.push(c.bm25Score);
+            if (c.vectorScore !== undefined)
+                vectorScores.push(c.vectorScore);
+        }
+        // Normalize
+        const bm25Normalized = minMaxNormalize(bm25Scores);
+        const vectorNormalized = minMaxNormalize(vectorScores);
+        // Build a map from raw score to normalized score
+        let bm25Idx = 0;
+        let vectorIdx = 0;
+        const bm25NormMap = new Map();
+        const vectorNormMap = new Map();
+        // Since multiple candidates can have the same raw score, use arrays
+        for (const c of candidates.values()) {
+            if (c.bm25Score !== undefined) {
+                if (!bm25NormMap.has(c.bm25Score))
+                    bm25NormMap.set(c.bm25Score, []);
+                bm25NormMap.get(c.bm25Score).push(bm25Normalized[bm25Idx++]);
+            }
+            if (c.vectorScore !== undefined) {
+                if (!vectorNormMap.has(c.vectorScore))
+                    vectorNormMap.set(c.vectorScore, []);
+                vectorNormMap.get(c.vectorScore).push(vectorNormalized[vectorIdx++]);
+            }
+        }
+        // Reset counters for consumption
+        const bm25NormCounters = new Map();
+        const vectorNormCounters = new Map();
+        const results = [];
+        // Re-iterate to assign normalized scores in order
+        bm25Idx = 0;
+        vectorIdx = 0;
+        for (const c of candidates.values()) {
+            let normBm25 = 0;
+            let normVector = 0;
+            if (c.bm25Score !== undefined) {
+                normBm25 = bm25Normalized[bm25Idx++];
+            }
+            if (c.vectorScore !== undefined) {
+                normVector = vectorNormalized[vectorIdx++];
+            }
+            const fusedScore = alpha * normVector + (1 - alpha) * normBm25;
+            const hasBoth = c.bm25Score !== undefined && c.vectorScore !== undefined;
+            results.push({
+                ...c.result,
+                score: fusedScore,
+                matchType: hasBoth ? 'hybrid' : (c.vectorScore !== undefined ? 'semantic' : c.result.matchType),
+                bm25Score: c.bm25Score,
+                vectorScore: c.vectorScore,
+            });
+        }
+        return results;
+    }
+    /**
+     * Reciprocal Rank Fusion.
+     * rrf_score(d) = sum(1 / (k + rank_i(d))) for each ranking
+     */
+    rrfFusion(candidates) {
+        const k = this.config.rrfK;
+        const results = [];
+        for (const c of candidates.values()) {
+            let rrfScore = 0;
+            if (c.bm25Rank !== undefined) {
+                rrfScore += 1 / (k + c.bm25Rank);
+            }
+            if (c.vectorRank !== undefined) {
+                rrfScore += 1 / (k + c.vectorRank);
+            }
+            const hasBoth = c.bm25Rank !== undefined && c.vectorRank !== undefined;
+            results.push({
+                ...c.result,
+                score: rrfScore,
+                matchType: hasBoth ? 'hybrid' : (c.vectorRank !== undefined ? 'semantic' : c.result.matchType),
+                bm25Score: c.bm25Score,
+                vectorScore: c.vectorScore,
+            });
+        }
+        return results;
+    }
+    /**
+     * Apply cross-encoder reranking to search results.
+     * Returns results unchanged if reranker is not configured, disabled, or errors.
+     */
+    async applyReranking(query, results) {
+        if (!this.rerankerConfig || !this.rerankerConfig.enabled) {
+            return results;
+        }
+        const { provider, topN = 10, candidatePool = 50 } = this.rerankerConfig;
+        // Take the top candidatePool results for reranking
+        const candidates = results.slice(0, candidatePool);
+        if (candidates.length === 0)
+            return results;
+        // Build rerank documents from search results
+        const documents = candidates.map((r, i) => ({
+            id: `${i}`,
+            text: this.buildRerankText(r),
+        }));
+        try {
+            const rerankResults = await provider.rerank(query, documents);
+            // Build a map from index to rerank score
+            const scoreMap = new Map();
+            for (const rr of rerankResults) {
+                scoreMap.set(rr.index, rr.score);
+            }
+            // Update candidate results with rerank scores
+            const reranked = [];
+            for (let i = 0; i < candidates.length; i++) {
+                const rerankScore = scoreMap.get(i);
+                if (rerankScore !== undefined) {
+                    reranked.push({
+                        ...candidates[i],
+                        score: rerankScore,
+                        rerankScore,
+                    });
+                }
+            }
+            // Sort by reranker score descending
+            reranked.sort((a, b) => b.score - a.score);
+            // Return top N
+            return reranked.slice(0, topN);
+        }
+        catch {
+            // Graceful fallback: return original results if reranker errors
+            return results;
+        }
+    }
+    /** Build text for reranking from a search result's symbol metadata. */
+    buildRerankText(result) {
+        const parts = [];
+        const { symbol } = result;
+        if (symbol.signature) {
+            parts.push(symbol.signature);
+        }
+        if (symbol.documentation) {
+            parts.push(symbol.documentation);
+        }
+        // Always include name and kind for context
+        parts.push(`${symbol.kind} ${symbol.name}`);
+        return parts.join('\n');
+    }
+    /** Create a document key for matching BM25 results to vector results. */
+    makeDocKey(filePath, symbolName, startLine) {
+        return `${filePath}:${symbolName}:${startLine}`;
+    }
+    matchPattern(filePath, pattern) {
+        if (pattern.startsWith('*')) {
+            return filePath.endsWith(pattern.slice(1));
+        }
+        if (pattern.endsWith('/**')) {
+            return filePath.startsWith(pattern.slice(0, -3));
+        }
+        if (pattern.endsWith('/*')) {
+            const dir = pattern.slice(0, -2);
+            return filePath.startsWith(dir) && !filePath.slice(dir.length + 1).includes('/');
+        }
+        return filePath.includes(pattern);
+    }
+}

package/dist/src/search/query-classifier.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Query classifier for adaptive alpha weighting in hybrid search.
+ * Detects whether a query is identifier-heavy, natural language, or mixed
+ * and returns a recommended alpha value.
+ */
+export type QueryType = 'identifier' | 'natural' | 'mixed';
+export interface QueryClassification {
+    type: QueryType;
+    alpha: number;
+}
+/**
+ * Classify a search query and return the recommended alpha value
+ * for CCS fusion.
+ *
+ * - identifier-heavy queries (camelCase, snake_case, etc.): alpha = 0.25 (favor BM25)
+ * - natural language queries ("authentication middleware"): alpha = 0.75 (favor vectors)
+ * - mixed queries ("fix CORS error in Express"): alpha = 0.55 (balanced)
+ */
+export declare function classifyQuery(query: string): QueryClassification;
+//# sourceMappingURL=query-classifier.d.ts.map

package/dist/src/search/query-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-classifier.d.ts","sourceRoot":"","sources":["../../../src/search/query-classifier.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,SAAS,GAAG,OAAO,CAAA;AAE1D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;CACd;AAuBD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,CAuBhE"}

package/dist/src/search/query-classifier.js

@@ -0,0 +1,58 @@
+/**
+ * Query classifier for adaptive alpha weighting in hybrid search.
+ * Detects whether a query is identifier-heavy, natural language, or mixed
+ * and returns a recommended alpha value.
+ */
+// Patterns that indicate code identifiers
+const CAMEL_CASE = /[a-z][a-zA-Z]*[A-Z]/;
+const PASCAL_CASE = /^[A-Z][a-zA-Z]+[A-Z]/;
+const SNAKE_CASE = /\w+_\w+/;
+const CONSTANT_CASE = /^[A-Z][A-Z0-9_]+$/;
+const DOT_NOTATION = /\w+\.\w+/;
+const OPERATOR_TOKENS = /(::|->|=>|#)/;
+/**
+ * Check if a token looks like a code identifier.
+ */
+function isIdentifierToken(token) {
+    if (CAMEL_CASE.test(token))
+        return true;
+    if (PASCAL_CASE.test(token))
+        return true;
+    if (SNAKE_CASE.test(token))
+        return true;
+    if (CONSTANT_CASE.test(token))
+        return true;
+    if (DOT_NOTATION.test(token))
+        return true;
+    if (OPERATOR_TOKENS.test(token))
+        return true;
+    return false;
+}
+/**
+ * Classify a search query and return the recommended alpha value
+ * for CCS fusion.
+ *
+ * - identifier-heavy queries (camelCase, snake_case, etc.): alpha = 0.25 (favor BM25)
+ * - natural language queries ("authentication middleware"): alpha = 0.75 (favor vectors)
+ * - mixed queries ("fix CORS error in Express"): alpha = 0.55 (balanced)
+ */
+export function classifyQuery(query) {
+    const tokens = query.split(/\s+/).filter(t => t.length > 0);
+    if (tokens.length === 0) {
+        return { type: 'natural', alpha: 0.75 };
+    }
+    let identifierCount = 0;
+    for (const token of tokens) {
+        if (isIdentifierToken(token)) {
+            identifierCount++;
+        }
+    }
+    const ratio = identifierCount / tokens.length;
+    if (ratio > 0.5) {
+        return { type: 'identifier', alpha: 0.25 };
+    }
+    if (ratio < 0.2) {
+        return { type: 'natural', alpha: 0.75 };
+    }
+    return { type: 'mixed', alpha: 0.55 };
+}

package/dist/src/search/score-normalizer.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Min-max score normalization for hybrid search fusion.
+ * Normalizes scores to [0, 1] range for CCS combination.
+ */
+/**
+ * Apply min-max normalization to an array of scores.
+ *
+ * normalized = (score - min) / (max - min)
+ *
+ * Edge cases:
+ * - Empty array → []
+ * - Single result → [1.0]
+ * - All same scores → all 1.0
+ */
+export declare function minMaxNormalize(scores: number[]): number[];
+//# sourceMappingURL=score-normalizer.d.ts.map

package/dist/src/search/score-normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"score-normalizer.d.ts","sourceRoot":"","sources":["../../../src/search/score-normalizer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAW1D"}

package/dist/src/search/score-normalizer.js

@@ -0,0 +1,26 @@
+/**
+ * Min-max score normalization for hybrid search fusion.
+ * Normalizes scores to [0, 1] range for CCS combination.
+ */
+/**
+ * Apply min-max normalization to an array of scores.
+ *
+ * normalized = (score - min) / (max - min)
+ *
+ * Edge cases:
+ * - Empty array → []
+ * - Single result → [1.0]
+ * - All same scores → all 1.0
+ */
+export function minMaxNormalize(scores) {
+    if (scores.length === 0)
+        return [];
+    if (scores.length === 1)
+        return [1.0];
+    const min = Math.min(...scores);
+    const max = Math.max(...scores);
+    const range = max - min;
+    if (range === 0)
+        return scores.map(() => 1.0);
+    return scores.map(s => (s - min) / range);
+}