lsp-intelligence 0.1.2 → 0.2.0

package/dist/search/families/behaviorFamilies.js

@@ -0,0 +1,90 @@
+/**
+ * Behavior families — redesigned with classifier/expansion split.
+ *
+ * classifierTerms: strong terms only. Weak words (use, get, set, call, run, make)
+ * must NEVER appear here. These drive mode routing.
+ *
+ * expansionTerms: broader lexical expansion for recall. May include weaker terms.
+ */
+export const BEHAVIOR_FAMILIES = [
+    {
+        id: 'auth_permission',
+        classifierTerms: ['permission', 'auth', 'authorize', 'guard', 'access', 'role', 'acl'],
+        expansionTerms: ['can', 'allow', 'deny', 'policy', 'privilege', 'protect', 'secure'],
+        fileHints: ['auth', 'permission', 'guard', 'access', 'policy', 'acl'],
+        symbolHints: ['permission', 'guard', 'authorize', 'protect', 'allow'],
+    },
+    {
+        id: 'validation',
+        classifierTerms: ['valid', 'validate', 'verify', 'assert', 'sanitize', 'schema'],
+        expansionTerms: ['parse', 'conform', 'ensure', 'require', 'constraint', 'check'],
+        fileHints: ['valid', 'verify', 'assert', 'sanitize', 'schema'],
+        symbolHints: ['valid', 'verify', 'assert', 'schema'],
+    },
+    {
+        id: 'error_handling',
+        classifierTerms: ['error', 'exception', 'boundary', 'recover', 'fallback'],
+        expansionTerms: ['fail', 'throw', 'sentinel', 'catch', 'handle'],
+        fileHints: ['error', 'handler', 'boundary', 'fallback', 'recovery'],
+        symbolHints: ['error', 'handle', 'recover', 'fallback', 'boundary'],
+    },
+    {
+        id: 'fetching',
+        classifierTerms: ['fetch', 'endpoint', 'api', 'request', 'http'],
+        expansionTerms: ['load', 'query', 'download', 'post', 'ajax', 'invoke'],
+        fileHints: ['api', 'fetch', 'service', 'client', 'endpoint', 'request'],
+        symbolHints: ['fetch', 'api', 'endpoint', 'request', 'service'],
+    },
+    {
+        id: 'state_management',
+        classifierTerms: ['redux', 'store', 'reducer', 'slice', 'dispatch'],
+        expansionTerms: ['action', 'thunk', 'selector', 'middleware', 'subscribe', 'state'],
+        fileHints: ['store', 'reducer', 'slice', 'duck', 'redux'],
+        symbolHints: ['reducer', 'slice', 'dispatch', 'selector', 'thunk'],
+    },
+    {
+        id: 'feature_flags',
+        classifierTerms: ['feature', 'flag', 'toggle', 'experiment', 'launch'],
+        expansionTerms: ['switch', 'variant', 'rollout', 'canary', 'gate', 'dark'],
+        fileHints: ['feature', 'flag', 'toggle', 'gate', 'experiment'],
+        symbolHints: ['feature', 'flag', 'toggle', 'gate', 'enabled'],
+    },
+    {
+        id: 'retry_backoff',
+        classifierTerms: ['retry', 'backoff', 'debounce', 'throttle', 'ratelimit'],
+        expansionTerms: ['exponential', 'delay', 'cooldown', 'timeout', 'interval', 'limit'],
+        fileHints: ['retry', 'backoff', 'throttle', 'debounce', 'rate'],
+        symbolHints: ['retry', 'backoff', 'debounce', 'throttle', 'delay'],
+    },
+    {
+        id: 'caching',
+        classifierTerms: ['cache', 'memoize', 'persist', 'ttl', 'lru'],
+        expansionTerms: ['memo', 'invalidate', 'expire', 'warm', 'preload', 'stale', 'store'],
+        fileHints: ['cache', 'memo', 'persist', 'storage'],
+        symbolHints: ['cache', 'memo', 'memoize', 'persist'],
+    },
+];
+/**
+ * Score a set of tokens against all families.
+ * Uses only classifierTerms for strong matching.
+ * Returns per-family scores.
+ */
+export function scoreFamilies(tokens) {
+    const scores = {};
+    for (const family of BEHAVIOR_FAMILIES) {
+        let score = 0;
+        for (const token of tokens) {
+            // Classifier terms: strong match
+            for (const ct of family.classifierTerms) {
+                if (ct === token)
+                    score += 3;
+                else if (ct.startsWith(token) || token.startsWith(ct))
+                    score += 1;
+            }
+        }
+        if (score > 0)
+            scores[family.id] = score;
+    }
+    return scores;
+}
+//# sourceMappingURL=behaviorFamilies.js.map

package/dist/search/families/behaviorFamilies.js.map

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

package/dist/search/index/declarationIndex.d.ts

@@ -0,0 +1,6 @@
+import type { DeclarationIndexEntry } from '../types.js';
+/**
+ * Build declaration index entries for a single file.
+ * Uses TypeScript compiler AST, not regex.
+ */
+export declare function indexFileDeclarations(filePath: string): DeclarationIndexEntry[];

package/dist/search/index/declarationIndex.js

@@ -0,0 +1,13 @@
+import { parseSourceFile } from '../../analysis/ts/parseSourceFile.js';
+import { extractDeclarations } from '../../analysis/ts/extractDeclarations.js';
+/**
+ * Build declaration index entries for a single file.
+ * Uses TypeScript compiler AST, not regex.
+ */
+export function indexFileDeclarations(filePath) {
+    const sf = parseSourceFile(filePath);
+    if (!sf)
+        return [];
+    return extractDeclarations(sf);
+}
+//# sourceMappingURL=declarationIndex.js.map

package/dist/search/index/declarationIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declarationIndex.js","sourceRoot":"","sources":["../../../src/search/index/declarationIndex.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAG/E;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,MAAM,EAAE,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACrC,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,CAAC;IACnB,OAAO,mBAAmB,CAAC,EAAE,CAAC,CAAC;AACjC,CAAC"}

package/dist/search/index/types.d.ts

@@ -0,0 +1 @@
+export type { DeclarationIndexEntry, UsageIndexEntry, IndexedFile, WorkspaceIndex, } from '../types.js';

package/dist/search/index/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/search/index/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/search/index/types.ts"],"names":[],"mappings":""}

package/dist/search/index/usageIndex.d.ts

@@ -0,0 +1,6 @@
+import type { UsageIndexEntry } from '../types.js';
+/**
+ * Build usage index entries for a single file.
+ * Indexes call expressions, member calls, imports, JSX tags using TS compiler AST.
+ */
+export declare function indexFileUsages(filePath: string): UsageIndexEntry[];

package/dist/search/index/usageIndex.js

@@ -0,0 +1,13 @@
+import { parseSourceFile } from '../../analysis/ts/parseSourceFile.js';
+import { extractUsages } from '../../analysis/ts/extractUsages.js';
+/**
+ * Build usage index entries for a single file.
+ * Indexes call expressions, member calls, imports, JSX tags using TS compiler AST.
+ */
+export function indexFileUsages(filePath) {
+    const sf = parseSourceFile(filePath);
+    if (!sf)
+        return [];
+    return extractUsages(sf);
+}
+//# sourceMappingURL=usageIndex.js.map

package/dist/search/index/usageIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usageIndex.js","sourceRoot":"","sources":["../../../src/search/index/usageIndex.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAGnE;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,MAAM,EAAE,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACrC,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,CAAC;IACnB,OAAO,aAAa,CAAC,EAAE,CAAC,CAAC;AAC3B,CAAC"}

package/dist/search/index/workspaceIndex.d.ts

@@ -0,0 +1,8 @@
+import type { SearchScope, WorkspaceIndex } from '../types.js';
+/**
+ * Get or build a workspace index for the given scope.
+ * Uses per-file mtime to invalidate stale entries — no TTL.
+ */
+export declare function getWorkspaceIndex(scope: SearchScope, opts?: {
+    forceRefresh?: boolean;
+}): WorkspaceIndex;

package/dist/search/index/workspaceIndex.js

@@ -0,0 +1,91 @@
+import * as fs from 'fs';
+import { collectScopeFiles } from '../../resolve/searchScope.js';
+import { indexFileDeclarations } from './declarationIndex.js';
+import { indexFileUsages } from './usageIndex.js';
+// Per-workspace cache with per-file mtime invalidation
+let cachedIndex = null;
+/**
+ * Get or build a workspace index for the given scope.
+ * Uses per-file mtime to invalidate stale entries — no TTL.
+ */
+export function getWorkspaceIndex(scope, opts) {
+    const root = scope.roots[0] ?? '';
+    // Full refresh if root changed or forced
+    if (!cachedIndex || cachedIndex.root !== root || opts?.forceRefresh) {
+        cachedIndex = buildFreshIndex(scope);
+        return cachedIndex;
+    }
+    // Incremental: check mtime per file, re-index changed files
+    const scopeFiles = collectScopeFiles(scope);
+    let changed = false;
+    for (const filePath of scopeFiles) {
+        try {
+            const mtime = fs.statSync(filePath).mtimeMs;
+            const existing = cachedIndex.files.get(filePath);
+            if (!existing || existing.mtimeMs !== mtime) {
+                // File is new or changed — re-index
+                const declarations = indexFileDeclarations(filePath);
+                const usages = indexFileUsages(filePath);
+                cachedIndex.files.set(filePath, { filePath, mtimeMs: mtime, declarations, usages });
+                changed = true;
+            }
+        }
+        catch {
+            // File may have been deleted
+            if (cachedIndex.files.has(filePath)) {
+                cachedIndex.files.delete(filePath);
+                changed = true;
+            }
+        }
+    }
+    // Remove files no longer in scope
+    const scopeSet = new Set(scopeFiles);
+    for (const key of cachedIndex.files.keys()) {
+        if (!scopeSet.has(key)) {
+            cachedIndex.files.delete(key);
+            changed = true;
+        }
+    }
+    // Rebuild flat arrays if anything changed
+    if (changed) {
+        rebuildFlatArrays(cachedIndex);
+    }
+    return cachedIndex;
+}
+function buildFreshIndex(scope) {
+    const root = scope.roots[0] ?? '';
+    const files = new Map();
+    const scopeFiles = collectScopeFiles(scope);
+    for (const filePath of scopeFiles) {
+        try {
+            const mtime = fs.statSync(filePath).mtimeMs;
+            const declarations = indexFileDeclarations(filePath);
+            const usages = indexFileUsages(filePath);
+            files.set(filePath, { filePath, mtimeMs: mtime, declarations, usages });
+        }
+        catch {
+            // Skip files that can't be read/parsed
+        }
+    }
+    const index = {
+        root,
+        builtAt: Date.now(),
+        files,
+        declarations: [],
+        usages: [],
+    };
+    rebuildFlatArrays(index);
+    return index;
+}
+function rebuildFlatArrays(index) {
+    const declarations = [];
+    const usages = [];
+    for (const file of index.files.values()) {
+        declarations.push(...file.declarations);
+        usages.push(...file.usages);
+    }
+    index.declarations = declarations;
+    index.usages = usages;
+    index.builtAt = Date.now();
+}
+//# sourceMappingURL=workspaceIndex.js.map

package/dist/search/index/workspaceIndex.js.map

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

package/dist/search/query/parseQuery.d.ts

@@ -0,0 +1,9 @@
+import type { QueryIR, SearchPlan } from '../types.js';
+/**
+ * Parse a raw query string into a structured QueryIR.
+ * Extracts three channels: NL tokens, exact identifiers, structural cues.
+ */
+export declare function parseQuery(raw: string, opts?: {
+    forcedMode?: SearchPlan['mode'] | 'auto';
+    forcedFamily?: string;
+}): QueryIR;

package/dist/search/query/parseQuery.js

@@ -0,0 +1,244 @@
+import { scoreFamilies } from '../families/behaviorFamilies.js';
+// Short family names (from find_code schema) → real family IDs
+const FAMILY_ALIASES = {
+    auth: 'auth_permission',
+    errors: 'error_handling',
+    state: 'state_management',
+    flags: 'feature_flags',
+    retry: 'retry_backoff',
+    validation: 'validation',
+    fetching: 'fetching',
+    caching: 'caching',
+};
+// Structural cue words — preserved, NOT removed as stop words
+const STRUCTURAL_CUES = new Set([
+    'conditional', 'conditionally', 'if', 'return', 'returns', 'cleanup',
+    'callback', 'without', 'inside', 'nested', 'loop', 'async', 'await',
+    'try', 'catch', 'switch', 'default', 'throw', 'promise',
+]);
+// NL stop words — only removed from the NL channel
+const STOP_WORDS = new Set([
+    'a', 'an', 'the', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+    'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could',
+    'should', 'may', 'might', 'can', 'shall', 'to', 'of', 'in', 'for',
+    'on', 'with', 'at', 'by', 'from', 'as', 'into', 'through', 'during',
+    'where', 'how', 'what', 'which', 'who', 'when', 'why',
+    'all', 'each', 'every', 'both', 'few', 'more', 'most', 'other',
+    'some', 'such', 'no', 'not', 'only', 'own', 'same', 'so', 'than',
+    'too', 'very', 'just', 'we', 'they', 'i', 'my', 'our', 'that',
+    'this', 'these', 'those', 'me', 'him', 'her', 'it', 'its',
+]);
+// Identifier pattern: camelCase, PascalCase, dotted (Promise.all, React.useEffect)
+const IDENTIFIER_PATTERN = /\b([A-Z][a-zA-Z0-9]*(?:\.[a-zA-Z][a-zA-Z0-9]*)*|[a-z][a-zA-Z0-9]*(?:\.[a-zA-Z][a-zA-Z0-9]*)*)\b/g;
+// Hook name pattern
+const HOOK_PATTERN = /^use[A-Z]/;
+// Structural predicate mapping from cue words
+const PREDICATE_MAP = {
+    conditional: ['conditional'],
+    conditionally: ['conditional'],
+    if: ['conditional'],
+    return: [], // phrase-based: only fires in combination (returns + cleanup, etc.)
+    returns: [], // phrase-based: only fires in combination
+    cleanup: [], // phrase-based: returns + cleanup → returns-cleanup
+    callback: [], // phrase-based: callback + hook identifier → hook-callback
+    try: ['has-try-catch'],
+    catch: ['has-try-catch'],
+    without: [], // modifier — inverts next predicate
+    loop: ['await-in-loop'],
+    switch: ['switch-no-default'],
+    default: ['switch-no-default'],
+    hook: ['inside-hook'],
+    nested: [],
+    async: [],
+    await: ['await-in-loop'],
+    promise: [],
+    throw: [],
+};
+/**
+ * Parse a raw query string into a structured QueryIR.
+ * Extracts three channels: NL tokens, exact identifiers, structural cues.
+ */
+export function parseQuery(raw, opts) {
+    const words = raw.split(/\s+/).filter(Boolean);
+    // --- Channel 1: Exact identifiers ---
+    const exactIdentifiers = [];
+    const dottedIdentifiers = [];
+    for (const word of words) {
+        const clean = word.replace(/[^a-zA-Z0-9.]/g, '');
+        if (!clean)
+            continue;
+        // Dotted identifier: Promise.all, React.useEffect
+        if (clean.includes('.') && /^[A-Za-z]/.test(clean)) {
+            dottedIdentifiers.push(clean);
+            continue;
+        }
+        // CamelCase/PascalCase identifier (not a plain lowercase word)
+        if (/^[A-Z]/.test(clean) || (HOOK_PATTERN.test(clean)) || (/[a-z][A-Z]/.test(clean) && clean.length > 3)) {
+            exactIdentifiers.push(clean);
+        }
+    }
+    // --- Channel 2: Structural cues ---
+    const structuralPredicates = [];
+    const codeTokens = [];
+    const hasWithout = words.some((w) => w.toLowerCase() === 'without');
+    for (const word of words) {
+        const lower = word.toLowerCase().replace(/[^a-z]/g, '');
+        if (STRUCTURAL_CUES.has(lower)) {
+            codeTokens.push(lower);
+            const preds = PREDICATE_MAP[lower] ?? [];
+            for (const pred of preds) {
+                // Handle "without" modifier
+                if (hasWithout && pred === 'returns-cleanup') {
+                    if (!structuralPredicates.includes('no-cleanup'))
+                        structuralPredicates.push('no-cleanup');
+                }
+                else if (hasWithout && pred === 'has-try-catch') {
+                    if (!structuralPredicates.includes('no-try-catch'))
+                        structuralPredicates.push('no-try-catch');
+                }
+                else {
+                    if (!structuralPredicates.includes(pred))
+                        structuralPredicates.push(pred);
+                }
+            }
+        }
+    }
+    // Phrase-based structural inference — requires combinations, not isolated keywords.
+    // This prevents "returns" alone from implying returns-function.
+    const hasHookId = exactIdentifiers.some((id) => HOOK_PATTERN.test(id));
+    if (codeTokens.includes('cleanup')) {
+        if (codeTokens.includes('returns') || codeTokens.includes('return')) {
+            // "returns cleanup" or "return cleanup"
+            if (hasWithout) {
+                if (!structuralPredicates.includes('no-cleanup'))
+                    structuralPredicates.push('no-cleanup');
+            }
+            else {
+                if (!structuralPredicates.includes('returns-cleanup'))
+                    structuralPredicates.push('returns-cleanup');
+            }
+        }
+        else if (hasWithout) {
+            // "without cleanup" (no returns keyword needed)
+            if (!structuralPredicates.includes('no-cleanup'))
+                structuralPredicates.push('no-cleanup');
+        }
+    }
+    if (codeTokens.includes('returns') || codeTokens.includes('return')) {
+        if (codeTokens.includes('callback') || hasHookId) {
+            // "returns callback" or "useEffect ... returns"
+            if (!structuralPredicates.includes('returns-function'))
+                structuralPredicates.push('returns-function');
+        }
+    }
+    if (codeTokens.includes('callback') && hasHookId) {
+        // "useEffect callback" — hook + callback together
+        if (!structuralPredicates.includes('hook-callback'))
+            structuralPredicates.push('hook-callback');
+    }
+    // Hook identifier + any structural predicates → add hook-callback context
+    if (hasHookId && structuralPredicates.length > 0) {
+        if (!structuralPredicates.includes('hook-callback')) {
+            structuralPredicates.push('hook-callback');
+        }
+    }
+    // --- Channel 3: NL tokens ---
+    const nlTokens = [];
+    for (const word of words) {
+        const lower = word.toLowerCase().replace(/[^a-z]/g, '');
+        if (!lower || lower.length < 2)
+            continue;
+        if (STOP_WORDS.has(lower))
+            continue;
+        // Don't add exact identifiers to NL channel
+        if (exactIdentifiers.includes(word) || dottedIdentifiers.includes(word))
+            continue;
+        nlTokens.push(lower);
+    }
+    // --- Phrases ---
+    const phrases = extractPhrases(raw);
+    // --- Family scoring ---
+    const allTerms = [...nlTokens, ...codeTokens];
+    let familyScores = scoreFamilies(allTerms);
+    // Apply forced family (resolve short alias → real ID)
+    if (opts?.forcedFamily) {
+        const resolvedFamily = FAMILY_ALIASES[opts.forcedFamily] ?? opts.forcedFamily;
+        familyScores[resolvedFamily] = (familyScores[resolvedFamily] ?? 0) + 10;
+    }
+    // --- Mode routing ---
+    const identifierScore = exactIdentifiers.length * 3 + dottedIdentifiers.length * 3;
+    const structuralScore = structuralPredicates.length * 2 + codeTokens.length;
+    const behaviorScore = Object.values(familyScores).reduce((s, v) => s + v, 0);
+    let mode;
+    let modeConfidence;
+    const routingReasons = [];
+    if (opts?.forcedMode && opts.forcedMode !== 'auto') {
+        mode = opts.forcedMode;
+        modeConfidence = 'high';
+        routingReasons.push(`forced mode: ${mode}`);
+    }
+    else {
+        // Determine mode from scores
+        const hasIdentifiers = identifierScore > 0;
+        const hasStructural = structuralScore > 2;
+        const hasBehavior = behaviorScore > 2;
+        if (hasIdentifiers && hasStructural) {
+            mode = 'structural'; // identifier + structural = structural (use identifier to locate, predicates to filter)
+            modeConfidence = 'high';
+            routingReasons.push('exact identifier detected', 'structural cues detected');
+        }
+        else if (hasIdentifiers && !hasBehavior) {
+            mode = 'identifier';
+            modeConfidence = 'high';
+            routingReasons.push('exact identifier detected', 'no strong behavior-family evidence');
+        }
+        else if (hasBehavior && hasStructural) {
+            mode = 'mixed';
+            modeConfidence = 'medium';
+            routingReasons.push('behavior family matched', 'structural cues detected');
+        }
+        else if (hasBehavior) {
+            mode = 'behavior';
+            modeConfidence = behaviorScore > 5 ? 'high' : 'medium';
+            routingReasons.push('behavior family matched');
+        }
+        else if (hasStructural) {
+            mode = 'structural';
+            modeConfidence = 'medium';
+            routingReasons.push('structural cues detected');
+        }
+        else if (hasIdentifiers) {
+            mode = 'identifier';
+            modeConfidence = 'medium';
+            routingReasons.push('identifier detected');
+        }
+        else {
+            mode = 'behavior'; // fallback
+            modeConfidence = 'low';
+            routingReasons.push('no strong signals, defaulting to behavior');
+        }
+    }
+    return {
+        raw,
+        nlTokens,
+        phrases,
+        exactIdentifiers,
+        dottedIdentifiers,
+        codeTokens,
+        familyScores,
+        structuralPredicates,
+        mode,
+        modeConfidence,
+        routingReasons,
+    };
+}
+function extractPhrases(raw) {
+    // Extract 2-3 word phrases that might be meaningful
+    const words = raw.toLowerCase().split(/\s+/).filter((w) => w.length > 2);
+    const phrases = [];
+    for (let i = 0; i < words.length - 1; i++) {
+        phrases.push(`${words[i]} ${words[i + 1]}`);
+    }
+    return phrases;
+}
+//# sourceMappingURL=parseQuery.js.map

package/dist/search/query/parseQuery.js.map

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

package/dist/search/query/planQuery.d.ts

@@ -0,0 +1,9 @@
+import type { QueryIR, SearchPlan } from '../types.js';
+/**
+ * Plan which retrievers to use based on the parsed query IR.
+ *
+ * Key design rule: the planner can choose ['identifier', 'structural']
+ * WITHOUT behavior retrieval. This is the core fix for queries like
+ * "useEffect that returns a cleanup callback conditionally".
+ */
+export declare function planQuery(ir: QueryIR): SearchPlan;

package/dist/search/query/planQuery.js

@@ -0,0 +1,58 @@
+/**
+ * Plan which retrievers to use based on the parsed query IR.
+ *
+ * Key design rule: the planner can choose ['identifier', 'structural']
+ * WITHOUT behavior retrieval. This is the core fix for queries like
+ * "useEffect that returns a cleanup callback conditionally".
+ */
+export function planQuery(ir) {
+    const retrievers = [];
+    const reasons = [];
+    switch (ir.mode) {
+        case 'behavior':
+            retrievers.push('behavior');
+            reasons.push('behavior family matched — searching declarations by concept');
+            break;
+        case 'identifier':
+            retrievers.push('identifier');
+            reasons.push('exact identifier detected — searching usage sites');
+            // Also add structural if any predicates exist
+            if (ir.structuralPredicates.length > 0) {
+                retrievers.push('structural');
+                reasons.push('structural predicates found — will filter by code shape');
+            }
+            break;
+        case 'structural':
+            // Identifier + structural: locate by identifier, filter by structure
+            if (ir.exactIdentifiers.length > 0 || ir.dottedIdentifiers.length > 0) {
+                retrievers.push('identifier');
+                reasons.push('using identifier to locate candidate sites');
+            }
+            retrievers.push('structural');
+            reasons.push('structural predicates will filter/rank results');
+            break;
+        case 'mixed':
+            retrievers.push('behavior');
+            reasons.push('behavior retrieval for concept matching');
+            if (ir.exactIdentifiers.length > 0 || ir.dottedIdentifiers.length > 0) {
+                retrievers.push('identifier');
+                reasons.push('identifier retrieval for exact API matches');
+            }
+            if (ir.structuralPredicates.length > 0) {
+                retrievers.push('structural');
+                reasons.push('structural predicates for shape filtering');
+            }
+            break;
+    }
+    // Ensure at least one retriever
+    if (retrievers.length === 0) {
+        retrievers.push('behavior');
+        reasons.push('fallback: no specific signals, using behavior search');
+    }
+    return {
+        mode: ir.mode,
+        retrievers,
+        reasons,
+    };
+}
+//# sourceMappingURL=planQuery.js.map

package/dist/search/query/planQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planQuery.js","sourceRoot":"","sources":["../../../src/search/query/planQuery.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,EAAW;IACnC,MAAM,UAAU,GAA6B,EAAE,CAAC;IAChD,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;QAChB,KAAK,UAAU;YACb,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,6DAA6D,CAAC,CAAC;YAC5E,MAAM;QAER,KAAK,YAAY;YACf,UAAU,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAC9B,OAAO,CAAC,IAAI,CAAC,mDAAmD,CAAC,CAAC;YAClE,8CAA8C;YAC9C,IAAI,EAAE,CAAC,oBAAoB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvC,UAAU,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;gBAC9B,OAAO,CAAC,IAAI,CAAC,yDAAyD,CAAC,CAAC;YAC1E,CAAC;YACD,MAAM;QAER,KAAK,YAAY;YACf,qEAAqE;YACrE,IAAI,EAAE,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACtE,UAAU,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;gBAC9B,OAAO,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;YAC7D,CAAC;YACD,UAAU,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAC9B,OAAO,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAC;YAC/D,MAAM;QAER,KAAK,OAAO;YACV,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC;YACxD,IAAI,EAAE,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACtE,UAAU,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;gBAC9B,OAAO,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;YAC7D,CAAC;YACD,IAAI,EAAE,CAAC,oBAAoB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvC,UAAU,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;gBAC9B,OAAO,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAC;YAC5D,CAAC;YACD,MAAM;IACV,CAAC;IAED,gCAAgC;IAChC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC5B,OAAO,CAAC,IAAI,CAAC,sDAAsD,CAAC,CAAC;IACvE,CAAC;IAED,OAAO;QACL,IAAI,EAAE,EAAE,CAAC,IAAI;QACb,UAAU;QACV,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/search/ranking/assessConfidence.d.ts

@@ -0,0 +1,6 @@
+import type { CodeCandidate, QueryIR, SearchPlan } from '../types.js';
+/**
+ * Assess overall confidence of the search results.
+ * High = strong signals from multiple sources. Low = weak/generic matches.
+ */
+export declare function assessConfidence(ranked: CodeCandidate[], ir: QueryIR, plan: SearchPlan): 'high' | 'medium' | 'low';