forge-server 0.1.0

package/dist/query/hybrid-search.js

@@ -0,0 +1,263 @@
+/**
+ * Hybrid search engine combining vector similarity + graph neighbor boost.
+ * Final scoring: 0.6 * vector_score + 0.3 * graph_centrality + 0.1 * recency_boost
+ *
+ * Phase 2: Full graph neighbor expansion.
+ * For each vector hit, traverse graph neighbors (IMPORTS, CALLS, TESTS, CO_MODIFIED)
+ * up to pivot_depth hops, collect neighbor file paths, and boost their scores.
+ * Graph centrality = number of times a file appears as a neighbor / max neighbor appearances.
+ */
+import { embedText } from '../ingestion/embedder.js';
+import { computeScore, deduplicateByFile, buildMatchReason } from './ranking.js';
+import { QUERY_FILE_NEIGHBORS, QUERY_FILE_HOTSPOTS } from './graph-queries.js';
+import { logger } from '../util/logger.js';
+/**
+ * Perform hybrid search over indexed code chunks.
+ * Returns deduplicated, ranked results by file.
+ */
+export async function hybridSearch(vectorStore, graphStore, options) {
+    const startTime = Date.now();
+    const { query, repoId, limit = 20, includeTests = false, pivotDepth = 2, vectorWeight = 0.55, graphWeight = 0.20, intent, } = options;
+    try {
+        // Step 1: Embed query
+        const queryVector = await embedText(query);
+        // Step 2: Vector search
+        const filter = {};
+        if (repoId)
+            filter['repo_id'] = repoId;
+        const vectorResults = await vectorStore.searchCodeChunks(queryVector, {
+            limit: limit * 2, // Get extra to allow deduplication
+            filter: Object.keys(filter).length > 0 ? filter : undefined,
+            scoreThreshold: 0.1,
+        });
+        // Step 3: Filter test files if needed
+        const filteredResults = vectorResults.filter(r => {
+            const payload = r.payload;
+            if (!includeTests) {
+                const fp = payload.file_path ?? '';
+                if (fp.includes('.spec.') || fp.includes('.test.') || fp.includes('__tests__')) {
+                    return false;
+                }
+            }
+            return true;
+        });
+        // Step 4: Graph neighbor expansion
+        // For each unique file in vector results, traverse graph neighbors and
+        // collect how often each neighboring file appears (centrality count).
+        const neighborCounts = new Map(); // filePath -> appearance count
+        const vectorFileSet = new Set(filteredResults.map(r => r.payload.file_path));
+        const graphHealthy = await graphStore.isHealthy();
+        if (!graphHealthy && repoId) {
+            logger.warn('Graph store is unhealthy — skipping graph expansion (vector-only mode)', {
+                query: query.slice(0, 50),
+                repoId,
+            });
+        }
+        if (graphHealthy && repoId) {
+            const uniqueFiles = Array.from(vectorFileSet);
+            // Query graph neighbors for each vector hit file
+            await Promise.all(uniqueFiles.map(async (filePath) => {
+                try {
+                    const result = await graphStore.query(QUERY_FILE_NEIGHBORS(filePath, repoId, pivotDepth));
+                    // Parse neighbor paths from raw result
+                    const rows = result.raw ?? [];
+                    for (const row of rows) {
+                        const neighborPath = extractNeighborPath(row);
+                        if (neighborPath && neighborPath !== filePath) {
+                            neighborCounts.set(neighborPath, (neighborCounts.get(neighborPath) ?? 0) + 1);
+                        }
+                    }
+                }
+                catch {
+                    // Graph query failure is non-fatal — degrade to vector-only
+                }
+            }));
+        }
+        // Step 5: Compute normalized graph centrality scores
+        const maxNeighborCount = neighborCounts.size > 0
+            ? Math.max(...neighborCounts.values())
+            : 1;
+        // Step 5b: Fetch file hotspot scores from FalkorDB File node commit_count
+        const hotspotMap = new Map(); // filePath -> normalized hotspot score
+        const useHotspot = intent === 'modify' || intent === 'debug' || intent === 'refactor';
+        if (useHotspot && graphHealthy && repoId) {
+            try {
+                const hotspotResult = await graphStore.query(QUERY_FILE_HOTSPOTS(repoId, 100));
+                const rows = hotspotResult.raw ?? [];
+                let maxCommitCount = 1;
+                // First pass: find max commit count
+                for (const row of rows) {
+                    const commitCount = extractHotspotCommitCount(row);
+                    if (commitCount > maxCommitCount)
+                        maxCommitCount = commitCount;
+                }
+                // Second pass: normalize
+                for (const row of rows) {
+                    const path = extractHotspotPath(row);
+                    const commitCount = extractHotspotCommitCount(row);
+                    if (path && commitCount > 0) {
+                        hotspotMap.set(path, commitCount / maxCommitCount);
+                    }
+                }
+            }
+            catch {
+                // Hotspot query failure is non-fatal
+                logger.debug('Hotspot query failed — skipping hotspot scoring');
+            }
+        }
+        // Step 6: Convert to ScoredResult with combined scores
+        const scored = filteredResults.map(r => {
+            const payload = r.payload;
+            const filePath = payload.file_path;
+            // Graph score: normalized neighbor appearance count
+            // Files that appear as neighbors of many vector hits get boosted
+            const rawGraphScore = neighborCounts.get(filePath) ?? 0;
+            const graphCentrality = maxNeighborCount > 0 ? rawGraphScore / maxNeighborCount : 0;
+            // Hotspot score: normalized commit count (0 for read intent)
+            const hotspotScore = useHotspot ? (hotspotMap.get(filePath) ?? 0) : 0;
+            const { finalScore, recencyScore } = computeScore(r.score, graphCentrality, payload.indexed_at ?? Date.now(), vectorWeight, graphWeight, undefined, // recencyWeight — use default
+            hotspotScore, undefined, // hotspotWeight — use default
+            0, // observationScore — Phase 4
+            undefined // observationWeight — use default
+            );
+            return {
+                filePath,
+                repoId: payload.repo_id,
+                vectorScore: r.score,
+                graphScore: graphCentrality,
+                recencyScore,
+                hotspotScore,
+                observationScore: 0,
+                finalScore,
+                entityName: payload.entity_name,
+                entityType: payload.entity_type,
+                startLine: payload.start_line,
+                endLine: payload.end_line,
+                matchReason: buildMatchReason(r.score, graphCentrality, payload.entity_name, payload.entity_type, hotspotScore),
+                indexedAt: payload.indexed_at,
+            };
+        });
+        // Step 7: Add neighbor files that scored above threshold but weren't in vector results
+        // These are files boosted purely by graph centrality (indirect relevance)
+        for (const [neighborPath, count] of neighborCounts) {
+            if (vectorFileSet.has(neighborPath))
+                continue; // Already in vector results
+            // Skip test files if not requested
+            if (!includeTests) {
+                if (neighborPath.includes('.spec.') ||
+                    neighborPath.includes('.test.') ||
+                    neighborPath.includes('__tests__'))
+                    continue;
+            }
+            const normalizedCount = count / maxNeighborCount;
+            if (normalizedCount < 0.3)
+                continue; // Only include strongly-connected neighbors
+            const neighborHotspot = useHotspot ? (hotspotMap.get(neighborPath) ?? 0) : 0;
+            const { finalScore, recencyScore } = computeScore(0, // No direct vector score
+            normalizedCount, Date.now(), // Unknown indexed_at for neighbor-only results
+            vectorWeight, graphWeight, undefined, neighborHotspot, undefined, 0, undefined);
+            scored.push({
+                filePath: neighborPath,
+                repoId: repoId ?? '',
+                vectorScore: 0,
+                graphScore: normalizedCount,
+                recencyScore,
+                hotspotScore: neighborHotspot,
+                observationScore: 0,
+                finalScore,
+                entityName: null,
+                entityType: 'file_level',
+                startLine: 0,
+                endLine: 0,
+                matchReason: buildMatchReason(0, normalizedCount, null, 'file_level', neighborHotspot),
+                indexedAt: undefined,
+            });
+        }
+        // Step 8: Deduplicate by file, keep highest score per file
+        const deduplicated = deduplicateByFile(scored);
+        logger.debug('Hybrid search completed', {
+            query: query.slice(0, 50),
+            vectorHits: vectorResults.length,
+            filteredHits: filteredResults.length,
+            neighborFiles: neighborCounts.size,
+            uniqueFiles: deduplicated.length,
+            durationMs: Date.now() - startTime,
+        });
+        return {
+            results: deduplicated.slice(0, limit),
+            cacheHits: 0, // Tracked by FileContentCache in tool handler
+            executionTimeMs: Date.now() - startTime,
+        };
+    }
+    catch (err) {
+        logger.error('Hybrid search failed', { query: query.slice(0, 50), error: String(err) });
+        return {
+            results: [],
+            cacheHits: 0,
+            executionTimeMs: Date.now() - startTime,
+        };
+    }
+}
+/**
+ * Extract neighbor file path from a raw FalkorDB query result row.
+ * QUERY_FILE_NEIGHBORS returns: RETURN neighbor.path as path, ...
+ * FalkorDB non-compact format: [header, [rows], stats]
+ * Each row cell for an alias like `path` is a scalar string.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractNeighborPath(row) {
+    if (!row)
+        return null;
+    // Row is an array of cell values (one per column in SELECT)
+    // Column order: [path, rel_type, depth]
+    if (Array.isArray(row)) {
+        const first = row[0];
+        if (typeof first === 'string')
+            return first;
+    }
+    // Object row format (some parsers return keyed objects)
+    if (typeof row === 'object' && row !== null) {
+        if (typeof row.path === 'string')
+            return row.path;
+    }
+    return null;
+}
+/**
+ * Extract file path from a QUERY_FILE_HOTSPOTS result row.
+ * Column order: [path, commit_count, stability_score, change_velocity]
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractHotspotPath(row) {
+    if (!row)
+        return null;
+    if (Array.isArray(row)) {
+        const first = row[0];
+        if (typeof first === 'string')
+            return first;
+    }
+    if (typeof row === 'object' && row !== null) {
+        if (typeof row.path === 'string')
+            return row.path;
+    }
+    return null;
+}
+/**
+ * Extract commit_count from a QUERY_FILE_HOTSPOTS result row.
+ * Column order: [path, commit_count, stability_score, change_velocity]
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractHotspotCommitCount(row) {
+    if (!row)
+        return 0;
+    if (Array.isArray(row)) {
+        const second = row[1];
+        if (typeof second === 'number')
+            return second;
+    }
+    if (typeof row === 'object' && row !== null) {
+        if (typeof row.commit_count === 'number')
+            return row.commit_count;
+    }
+    return 0;
+}
+//# sourceMappingURL=hybrid-search.js.map

package/dist/query/hybrid-search.js.map

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

package/dist/query/intent-detector.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Query intent classifier using keyword matching (Phase 1).
+ * Classifies queries as: read | modify | debug | refactor
+ * Phase 4 will enhance with ML-based classification.
+ */
+import type { QueryIntent } from '../util/types.js';
+/**
+ * Detect the intent of a query string.
+ * Returns the intent category with highest keyword match count.
+ * Default: 'read' (safest, most common).
+ */
+export declare function detectIntent(query: string): QueryIntent;
+/**
+ * Get retrieval strategy adjustments based on intent.
+ * These affect ranking weights and result composition.
+ *
+ * Phase 4: 5-signal weights (vector, graph, recency, hotspot, observation).
+ *
+ * | Intent   | Vector | Graph | Recency | Hotspot | Observation |
+ * |----------|--------|-------|---------|---------|-------------|
+ * | read     | 0.55   | 0.20  | 0.05    | 0.10    | 0.10        |
+ * | modify   | 0.50   | 0.20  | 0.08    | 0.12    | 0.10        |
+ * | debug    | 0.40   | 0.25  | 0.05    | 0.10    | 0.20        |
+ * | refactor | 0.35   | 0.30  | 0.05    | 0.15    | 0.15        |
+ */
+export declare function getIntentStrategy(intent: QueryIntent): {
+    vectorWeight: number;
+    graphWeight: number;
+    recencyWeight: number;
+    hotspotWeight: number;
+    observationWeight: number;
+    includeTests: boolean;
+    expandDepth: number;
+};
+//# sourceMappingURL=intent-detector.d.ts.map

package/dist/query/intent-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent-detector.d.ts","sourceRoot":"","sources":["../../src/query/intent-detector.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA2BpD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAyBvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB,CA4CA"}

package/dist/query/intent-detector.js

@@ -0,0 +1,115 @@
+/**
+ * Query intent classifier using keyword matching (Phase 1).
+ * Classifies queries as: read | modify | debug | refactor
+ * Phase 4 will enhance with ML-based classification.
+ */
+const INTENT_KEYWORDS = {
+    debug: [
+        'error', 'bug', 'fix', 'broken', 'failing', 'crash', 'exception',
+        'undefined', 'null', 'TypeError', 'undefined is not', 'cannot read',
+        'stack trace', 'stacktrace', 'traceback', 'debug', 'diagnose', 'why is',
+        'not working', 'breaks', 'issue', 'problem', 'wrong', 'incorrect',
+    ],
+    refactor: [
+        'refactor', 'restructure', 'reorganize', 'extract', 'move', 'rename',
+        'split', 'merge', 'clean up', 'cleanup', 'simplify', 'optimize',
+        'performance', 'improve', 'better', 'smell', 'technical debt', 'dead code',
+        'duplicate', 'dry', 'abstract',
+    ],
+    modify: [
+        'add', 'implement', 'create', 'build', 'write', 'update', 'change',
+        'modify', 'edit', 'extend', 'enhance', 'feature', 'new', 'support',
+        'integrate', 'connect', 'wire', 'hook up', 'plug in', 'configure',
+    ],
+    read: [
+        'how', 'what', 'where', 'explain', 'understand', 'show', 'list',
+        'find', 'search', 'look', 'describe', 'overview', 'structure', 'schema',
+        'architecture', 'flow', 'logic', 'context', 'about', 'definition',
+    ],
+};
+/**
+ * Detect the intent of a query string.
+ * Returns the intent category with highest keyword match count.
+ * Default: 'read' (safest, most common).
+ */
+export function detectIntent(query) {
+    const lowerQuery = query.toLowerCase();
+    const scores = { debug: 0, refactor: 0, modify: 0, read: 0 };
+    for (const [intent, keywords] of Object.entries(INTENT_KEYWORDS)) {
+        for (const keyword of keywords) {
+            if (lowerQuery.includes(keyword)) {
+                scores[intent]++;
+            }
+        }
+    }
+    // Find intent with highest score
+    let maxScore = 0;
+    let detectedIntent = 'read';
+    // Priority: debug > refactor > modify > read (more specific wins on tie)
+    for (const intent of ['debug', 'refactor', 'modify', 'read']) {
+        if (scores[intent] > maxScore) {
+            maxScore = scores[intent];
+            detectedIntent = intent;
+        }
+    }
+    return detectedIntent;
+}
+/**
+ * Get retrieval strategy adjustments based on intent.
+ * These affect ranking weights and result composition.
+ *
+ * Phase 4: 5-signal weights (vector, graph, recency, hotspot, observation).
+ *
+ * | Intent   | Vector | Graph | Recency | Hotspot | Observation |
+ * |----------|--------|-------|---------|---------|-------------|
+ * | read     | 0.55   | 0.20  | 0.05    | 0.10    | 0.10        |
+ * | modify   | 0.50   | 0.20  | 0.08    | 0.12    | 0.10        |
+ * | debug    | 0.40   | 0.25  | 0.05    | 0.10    | 0.20        |
+ * | refactor | 0.35   | 0.30  | 0.05    | 0.15    | 0.15        |
+ */
+export function getIntentStrategy(intent) {
+    switch (intent) {
+        case 'debug':
+            return {
+                vectorWeight: 0.40,
+                graphWeight: 0.25,
+                recencyWeight: 0.05,
+                hotspotWeight: 0.10,
+                observationWeight: 0.20, // Observations are critical for debugging
+                includeTests: true, // Tests often show error scenarios
+                expandDepth: 3,
+            };
+        case 'refactor':
+            return {
+                vectorWeight: 0.35,
+                graphWeight: 0.30, // Blast radius is critical for refactoring
+                recencyWeight: 0.05,
+                hotspotWeight: 0.15, // Hotspots indicate high-churn areas
+                observationWeight: 0.15,
+                includeTests: true,
+                expandDepth: 3,
+            };
+        case 'modify':
+            return {
+                vectorWeight: 0.50,
+                graphWeight: 0.20,
+                recencyWeight: 0.08,
+                hotspotWeight: 0.12,
+                observationWeight: 0.10,
+                includeTests: false,
+                expandDepth: 2,
+            };
+        case 'read':
+        default:
+            return {
+                vectorWeight: 0.55,
+                graphWeight: 0.20,
+                recencyWeight: 0.05,
+                hotspotWeight: 0.10,
+                observationWeight: 0.10,
+                includeTests: false,
+                expandDepth: 2,
+            };
+    }
+}
+//# sourceMappingURL=intent-detector.js.map

package/dist/query/intent-detector.js.map

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

package/dist/query/ranking.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Result ranking and scoring for hybrid search.
+ * Phase 1: Vector score only (graph_centrality added in Phase 2).
+ * Phase 3: 4-signal scoring with hotspot.
+ * Phase 4: 5-signal scoring with observation relevance.
+ *
+ * Default weights: 0.55 vector + 0.20 graph + 0.05 recency + 0.10 hotspot + 0.10 observation
+ * All new weights are backward-compatible (default to 0).
+ */
+export interface ScoredResult {
+    filePath: string;
+    repoId: string;
+    vectorScore: number;
+    graphScore: number;
+    recencyScore: number;
+    hotspotScore: number;
+    observationScore: number;
+    finalScore: number;
+    entityName: string | null;
+    entityType: string;
+    startLine: number;
+    endLine: number;
+    matchReason: string;
+    indexedAt?: number;
+}
+/**
+ * Compute final ranking score combining up to 5 signals:
+ *   vector, graph, recency, hotspot, observation.
+ *
+ * Backward-compatible: hotspotScore and observationScore default to 0,
+ * with their weights redistributed to maintain consistent scoring
+ * when callers haven't been updated to supply them.
+ */
+export declare function computeScore(vectorScore: number, graphScore: number, indexedAt: number, vectorWeight?: number, graphWeight?: number, recencyWeight?: number, hotspotScore?: number, hotspotWeight?: number, observationScore?: number, observationWeight?: number): {
+    finalScore: number;
+    recencyScore: number;
+};
+/**
+ * Deduplicate results by file path, keeping the highest-scored entry per file.
+ */
+export declare function deduplicateByFile(results: ScoredResult[]): ScoredResult[];
+/**
+ * Split results into pivot files (full content) and skeletons (summaries) using actual token sizes.
+ * If fileSizes is provided (map of filePath -> estimated tokens), uses real sizes.
+ * Otherwise falls back to avgFileTokens estimate.
+ */
+export declare function splitPivotsAndSkeletons(results: ScoredResult[], tokenBudget: number, fileSizes?: Map<string, number>, avgFileTokens?: number): {
+    pivots: ScoredResult[];
+    skeletons: ScoredResult[];
+};
+/**
+ * Generate a human-readable match reason string.
+ * Phase 3: includes hotspot info.
+ * Phase 4: includes observation info.
+ */
+export declare function buildMatchReason(vectorScore: number, graphScore: number, entityName: string | null, entityType: string, hotspotScore?: number, observationScore?: number): string;
+//# sourceMappingURL=ranking.d.ts.map

package/dist/query/ranking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranking.d.ts","sourceRoot":"","sources":["../../src/query/ranking.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAWH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,YAAY,SAAgB,EAC5B,WAAW,SAAe,EAC1B,aAAa,SAAiB,EAC9B,YAAY,GAAE,MAAU,EACxB,aAAa,GAAE,MAAuB,EACtC,gBAAgB,GAAE,MAAU,EAC5B,iBAAiB,GAAE,MAA2B,GAC7C;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAa9C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAWzE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,YAAY,EAAE,EACvB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,aAAa,GAAE,MAAY,GAC1B;IAAE,MAAM,EAAE,YAAY,EAAE,CAAC;IAAC,SAAS,EAAE,YAAY,EAAE,CAAA;CAAE,CAgBvD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,MAAM,EAClB,YAAY,GAAE,MAAU,EACxB,gBAAgB,GAAE,MAAU,GAC3B,MAAM,CAkCR"}

package/dist/query/ranking.js

@@ -0,0 +1,109 @@
+/**
+ * Result ranking and scoring for hybrid search.
+ * Phase 1: Vector score only (graph_centrality added in Phase 2).
+ * Phase 3: 4-signal scoring with hotspot.
+ * Phase 4: 5-signal scoring with observation relevance.
+ *
+ * Default weights: 0.55 vector + 0.20 graph + 0.05 recency + 0.10 hotspot + 0.10 observation
+ * All new weights are backward-compatible (default to 0).
+ */
+const VECTOR_WEIGHT = 0.55;
+const GRAPH_WEIGHT = 0.20;
+const RECENCY_WEIGHT = 0.05;
+const HOTSPOT_WEIGHT = 0.10;
+const OBSERVATION_WEIGHT = 0.10;
+// Recency boost: files indexed within the last hour get a small boost
+const RECENCY_WINDOW_MS = 60 * 60 * 1000; // 1 hour
+/**
+ * Compute final ranking score combining up to 5 signals:
+ *   vector, graph, recency, hotspot, observation.
+ *
+ * Backward-compatible: hotspotScore and observationScore default to 0,
+ * with their weights redistributed to maintain consistent scoring
+ * when callers haven't been updated to supply them.
+ */
+export function computeScore(vectorScore, graphScore, indexedAt, vectorWeight = VECTOR_WEIGHT, graphWeight = GRAPH_WEIGHT, recencyWeight = RECENCY_WEIGHT, hotspotScore = 0, hotspotWeight = HOTSPOT_WEIGHT, observationScore = 0, observationWeight = OBSERVATION_WEIGHT) {
+    const now = Date.now();
+    const age = now - indexedAt;
+    const recencyScore = age < RECENCY_WINDOW_MS ? 1.0 - (age / RECENCY_WINDOW_MS) : 0;
+    const finalScore = vectorWeight * vectorScore +
+        graphWeight * graphScore +
+        recencyWeight * recencyScore +
+        hotspotWeight * hotspotScore +
+        observationWeight * observationScore;
+    return { finalScore, recencyScore };
+}
+/**
+ * Deduplicate results by file path, keeping the highest-scored entry per file.
+ */
+export function deduplicateByFile(results) {
+    const byFile = new Map();
+    for (const result of results) {
+        const existing = byFile.get(result.filePath);
+        if (!existing || result.finalScore > existing.finalScore) {
+            byFile.set(result.filePath, result);
+        }
+    }
+    return Array.from(byFile.values()).sort((a, b) => b.finalScore - a.finalScore);
+}
+/**
+ * Split results into pivot files (full content) and skeletons (summaries) using actual token sizes.
+ * If fileSizes is provided (map of filePath -> estimated tokens), uses real sizes.
+ * Otherwise falls back to avgFileTokens estimate.
+ */
+export function splitPivotsAndSkeletons(results, tokenBudget, fileSizes, avgFileTokens = 500) {
+    const pivots = [];
+    const skeletons = [];
+    let usedTokens = 0;
+    for (const result of results) {
+        const fileTokens = fileSizes?.get(result.filePath) ?? avgFileTokens;
+        if (usedTokens + fileTokens <= tokenBudget) {
+            pivots.push(result);
+            usedTokens += fileTokens;
+        }
+        else {
+            skeletons.push(result);
+        }
+    }
+    return { pivots, skeletons };
+}
+/**
+ * Generate a human-readable match reason string.
+ * Phase 3: includes hotspot info.
+ * Phase 4: includes observation info.
+ */
+export function buildMatchReason(vectorScore, graphScore, entityName, entityType, hotspotScore = 0, observationScore = 0) {
+    const parts = [];
+    if (vectorScore > 0.8) {
+        parts.push('high semantic similarity');
+    }
+    else if (vectorScore > 0.5) {
+        parts.push('semantic match');
+    }
+    else {
+        parts.push('partial semantic match');
+    }
+    if (graphScore > 0.5) {
+        parts.push('high graph centrality');
+    }
+    else if (graphScore > 0) {
+        parts.push('graph neighbor');
+    }
+    if (hotspotScore > 0.7) {
+        parts.push('change hotspot');
+    }
+    else if (hotspotScore > 0.3) {
+        parts.push('frequently changed');
+    }
+    if (observationScore > 0.5) {
+        parts.push('has relevant observations');
+    }
+    else if (observationScore > 0) {
+        parts.push('has observations');
+    }
+    if (entityName) {
+        parts.push(`entity: ${entityName} (${entityType})`);
+    }
+    return parts.join(', ');
+}
+//# sourceMappingURL=ranking.js.map

package/dist/query/ranking.js.map

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

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createForgeServer(): Promise<McpServer>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAqDpE,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,SAAS,CAAC,CAyP5D"}