codebase-context 1.6.2 → 1.8.0

package/dist/tools/search-codebase.js

@@ -0,0 +1,745 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { CodebaseSearcher } from '../core/search.js';
+import { buildEvidenceLock } from '../preflight/evidence-lock.js';
+import { shouldIncludePatternConflictCategory } from '../preflight/query-scope.js';
+import { isComplementaryPatternConflict, shouldSkipLegacyTestingFrameworkCategory } from '../patterns/semantics.js';
+import { assessSearchQuality } from '../core/search-quality.js';
+import { IndexCorruptedError } from '../errors/index.js';
+import { readMemoriesFile, withConfidence } from '../memory/store.js';
+import { InternalFileGraph } from '../utils/usage-tracker.js';
+import { RELATIONSHIPS_FILENAME } from '../constants/codebase-context.js';
+export const definition = {
+    name: 'search_codebase',
+    description: 'Search the indexed codebase. Returns ranked results and a searchQuality confidence summary. ' +
+        'IMPORTANT: Pass the intent="edit"|"refactor"|"migrate" to get preflight: edit readiness check with evidence gating.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Natural language search query'
+            },
+            intent: {
+                type: 'string',
+                enum: ['explore', 'edit', 'refactor', 'migrate'],
+                description: 'Optional. Use "edit", "refactor", or "migrate" to get the full preflight card before making changes.'
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum number of results to return (default: 5)',
+                default: 5
+            },
+            includeSnippets: {
+                type: 'boolean',
+                description: 'Include code snippets in results (default: false). If you need code, prefer read_file instead.',
+                default: false
+            },
+            filters: {
+                type: 'object',
+                description: 'Optional filters',
+                properties: {
+                    framework: {
+                        type: 'string',
+                        description: 'Filter by framework (angular, react, vue)'
+                    },
+                    language: {
+                        type: 'string',
+                        description: 'Filter by programming language'
+                    },
+                    componentType: {
+                        type: 'string',
+                        description: 'Filter by component type (component, service, directive, etc.)'
+                    },
+                    layer: {
+                        type: 'string',
+                        description: 'Filter by architectural layer (presentation, business, data, state, core, shared)'
+                    },
+                    tags: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Filter by tags'
+                    }
+                }
+            }
+        },
+        required: ['query']
+    }
+};
+export async function handle(args, ctx) {
+    const { query, limit, filters, intent, includeSnippets } = args;
+    const queryStr = typeof query === 'string' ? query.trim() : '';
+    if (!queryStr) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        status: 'error',
+                        errorCode: 'invalid_params',
+                        message: "Invalid params: 'query' is required and must be a non-empty string.",
+                        hint: "Provide a query like 'how are routes configured' or 'AlbumApiService'."
+                    }, null, 2)
+                }
+            ],
+            isError: true
+        };
+    }
+    if (ctx.indexState.status === 'indexing') {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        status: 'indexing',
+                        message: 'Index is still being built. Retry in a moment.',
+                        progress: ctx.indexState.indexer?.getProgress()
+                    }, null, 2)
+                }
+            ]
+        };
+    }
+    if (ctx.indexState.status === 'error') {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        status: 'error',
+                        message: `Indexing failed: ${ctx.indexState.error}`
+                    }, null, 2)
+                }
+            ]
+        };
+    }
+    const searcher = new CodebaseSearcher(ctx.rootPath);
+    let results;
+    const searchProfile = (intent && ['explore', 'edit', 'refactor', 'migrate'].includes(intent) ? intent : 'explore');
+    try {
+        results = await searcher.search(queryStr, limit || 5, filters, {
+            profile: searchProfile
+        });
+    }
+    catch (error) {
+        if (error instanceof IndexCorruptedError) {
+            console.error('[Auto-Heal] Index corrupted. Triggering full re-index...');
+            await ctx.performIndexing();
+            if (ctx.indexState.status === 'ready') {
+                console.error('[Auto-Heal] Success. Retrying search...');
+                const freshSearcher = new CodebaseSearcher(ctx.rootPath);
+                try {
+                    results = await freshSearcher.search(queryStr, limit || 5, filters, {
+                        profile: searchProfile
+                    });
+                }
+                catch (retryError) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    status: 'error',
+                                    message: `Auto-heal retry failed: ${retryError instanceof Error ? retryError.message : String(retryError)}`
+                                }, null, 2)
+                            }
+                        ]
+                    };
+                }
+            }
+            else {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                status: 'error',
+                                message: `Auto-heal failed: Indexing ended with status '${ctx.indexState.status}'`,
+                                error: ctx.indexState.error
+                            }, null, 2)
+                        }
+                    ]
+                };
+            }
+        }
+        else {
+            throw error; // Propagate unexpected errors
+        }
+    }
+    // Load memories for keyword matching, enriched with confidence
+    const allMemories = await readMemoriesFile(ctx.paths.memory);
+    const allMemoriesWithConf = withConfidence(allMemories);
+    const queryTerms = queryStr.toLowerCase().split(/\s+/).filter(Boolean);
+    const relatedMemories = allMemoriesWithConf
+        .filter((m) => {
+        const searchText = `${m.memory} ${m.reason}`.toLowerCase();
+        return queryTerms.some((term) => searchText.includes(term));
+    })
+        .sort((a, b) => b.effectiveConfidence - a.effectiveConfidence);
+    // Load intelligence data for enrichment (all intents, not just preflight)
+    let intelligence = null;
+    try {
+        const intelligenceContent = await fs.readFile(ctx.paths.intelligence, 'utf-8');
+        const parsed = JSON.parse(intelligenceContent);
+        if (typeof parsed === 'object' && parsed !== null) {
+            intelligence = parsed;
+        }
+    }
+    catch {
+        /* graceful degradation — intelligence file may not exist yet */
+    }
+    // Load relationships sidecar (preferred over intelligence.internalFileGraph)
+    let relationships = null;
+    try {
+        const relationshipsPath = path.join(path.dirname(ctx.paths.intelligence), RELATIONSHIPS_FILENAME);
+        const relationshipsContent = await fs.readFile(relationshipsPath, 'utf-8');
+        const parsed = JSON.parse(relationshipsContent);
+        if (typeof parsed === 'object' && parsed !== null) {
+            relationships = parsed;
+        }
+    }
+    catch {
+        /* graceful degradation — relationships sidecar may not exist yet */
+    }
+    // Helper to get imports graph from relationships sidecar (preferred) or intelligence
+    function getImportsGraph() {
+        if (relationships?.graph?.imports) {
+            return relationships.graph.imports;
+        }
+        if (intelligence?.internalFileGraph?.imports) {
+            return intelligence.internalFileGraph.imports;
+        }
+        return null;
+    }
+    function getImportDetailsGraph() {
+        if (relationships?.graph?.importDetails) {
+            return relationships.graph.importDetails;
+        }
+        const internalDetails = intelligence?.internalFileGraph?.importDetails;
+        if (internalDetails) {
+            return internalDetails;
+        }
+        return null;
+    }
+    function normalizeGraphPath(filePath) {
+        const normalized = filePath.replace(/\\/g, '/');
+        if (path.isAbsolute(filePath)) {
+            const rel = path.relative(ctx.rootPath, filePath).replace(/\\/g, '/');
+            if (rel && !rel.startsWith('..')) {
+                return rel;
+            }
+        }
+        return normalized.replace(/^\.\//, '');
+    }
+    function pathsMatch(a, b) {
+        return a === b || a.endsWith(b) || b.endsWith(a);
+    }
+    function computeIndexConfidence() {
+        let confidence = 'stale';
+        if (intelligence?.generatedAt) {
+            const indexAge = Date.now() - new Date(intelligence.generatedAt).getTime();
+            const hoursOld = indexAge / (1000 * 60 * 60);
+            if (hoursOld < 24) {
+                confidence = 'fresh';
+            }
+            else if (hoursOld < 168) {
+                confidence = 'aging';
+            }
+        }
+        return confidence;
+    }
+    function findImportDetail(details, importer, imported) {
+        if (!details)
+            return null;
+        const edges = details[importer];
+        if (!edges)
+            return null;
+        if (edges[imported])
+            return edges[imported];
+        let bestKey = null;
+        for (const depKey of Object.keys(edges)) {
+            if (!pathsMatch(depKey, imported))
+                continue;
+            if (!bestKey || depKey.length > bestKey.length) {
+                bestKey = depKey;
+            }
+        }
+        return bestKey ? edges[bestKey] : null;
+    }
+    // Impact breadth estimate from the import graph (used for risk assessment).
+    // 2-hop: direct importers (hop 1) + importers of importers (hop 2).
+    function computeImpactCandidates(resultPaths) {
+        const allImports = getImportsGraph();
+        if (!allImports)
+            return [];
+        const importDetails = getImportDetailsGraph();
+        const reverseImportsLocal = new Map();
+        for (const [file, deps] of Object.entries(allImports)) {
+            for (const dep of deps) {
+                if (!reverseImportsLocal.has(dep))
+                    reverseImportsLocal.set(dep, []);
+                reverseImportsLocal.get(dep).push(file);
+            }
+        }
+        const targets = resultPaths.map((rp) => normalizeGraphPath(rp));
+        const candidates = new Map();
+        const addCandidate = (file, hop, line) => {
+            const existing = candidates.get(file);
+            if (existing) {
+                if (existing.hop <= hop)
+                    return;
+            }
+            candidates.set(file, { file, hop, ...(line ? { line } : {}) });
+        };
+        const collectImporters = (target) => {
+            const matches = [];
+            for (const [dep, importers] of reverseImportsLocal) {
+                if (!pathsMatch(dep, target))
+                    continue;
+                for (const importer of importers) {
+                    matches.push({ importer, detail: findImportDetail(importDetails, importer, dep) });
+                }
+            }
+            return matches;
+        };
+        // Hop 1
+        const hop1Files = [];
+        for (const target of targets) {
+            for (const { importer, detail } of collectImporters(target)) {
+                addCandidate(importer, 1, detail?.line);
+            }
+        }
+        for (const candidate of candidates.values()) {
+            if (candidate.hop === 1)
+                hop1Files.push(candidate.file);
+        }
+        // Hop 2
+        for (const mid of hop1Files) {
+            for (const { importer, detail } of collectImporters(mid)) {
+                addCandidate(importer, 2, detail?.line);
+            }
+        }
+        return Array.from(candidates.values()).slice(0, 20);
+    }
+    // Build reverse import map from relationships sidecar (preferred) or intelligence graph
+    const reverseImports = new Map();
+    const importsGraph = getImportsGraph();
+    if (importsGraph) {
+        for (const [file, deps] of Object.entries(importsGraph)) {
+            for (const dep of deps) {
+                if (!reverseImports.has(dep))
+                    reverseImports.set(dep, []);
+                reverseImports.get(dep).push(file);
+            }
+        }
+    }
+    function buildRelationshipHints(result) {
+        const rPath = result.filePath;
+        // Graph keys are relative paths with forward slashes; normalize for comparison
+        const rPathNorm = path.relative(ctx.rootPath, rPath).replace(/\\/g, '/') || rPath.replace(/\\/g, '/');
+        // importedBy: files that import this result (reverse lookup), collect with counts
+        const importedByMap = new Map();
+        for (const [dep, importers] of reverseImports) {
+            if (dep === rPathNorm || dep.endsWith(rPathNorm) || rPathNorm.endsWith(dep)) {
+                for (const importer of importers) {
+                    importedByMap.set(importer, (importedByMap.get(importer) || 0) + 1);
+                }
+            }
+        }
+        // testedIn: heuristic — same basename with .spec/.test extension
+        const testedIn = [];
+        const baseName = path.basename(rPathNorm).replace(/\.[^.]+$/, '');
+        if (importsGraph) {
+            for (const file of Object.keys(importsGraph)) {
+                const fileBase = path.basename(file);
+                if ((fileBase.includes('.spec.') || fileBase.includes('.test.')) &&
+                    fileBase.startsWith(baseName)) {
+                    testedIn.push(file);
+                }
+            }
+        }
+        // Build condensed relationships
+        const condensedRel = {};
+        if (importedByMap.size > 0) {
+            condensedRel.importedByCount = importedByMap.size;
+        }
+        if (testedIn.length > 0) {
+            condensedRel.hasTests = true;
+        }
+        // Build hints object with capped arrays
+        const hintsObj = {};
+        // Rank importers by count descending, cap at 3
+        if (importedByMap.size > 0) {
+            const sortedCallers = Array.from(importedByMap.entries())
+                .sort((a, b) => b[1] - a[1])
+                .slice(0, 3)
+                .map(([file]) => file);
+            hintsObj.callers = sortedCallers;
+            hintsObj.consumers = sortedCallers; // Same data, different label
+        }
+        // Cap tests at 3
+        if (testedIn.length > 0) {
+            hintsObj.tests = testedIn.slice(0, 3);
+        }
+        // Return both condensed and hints (hints only included if non-empty)
+        const output = {};
+        if (Object.keys(condensedRel).length > 0) {
+            output.relationships = condensedRel;
+        }
+        if (Object.keys(hintsObj).length > 0) {
+            output.hints = hintsObj;
+        }
+        return output;
+    }
+    const searchQuality = assessSearchQuality(queryStr, results);
+    // Always-on edit preflight (lite): do not require intent and keep payload small.
+    let editPreflight = undefined;
+    if (intelligence && (!intent || intent === 'explore')) {
+        try {
+            const resultPaths = results.map((r) => r.filePath);
+            const impactCandidates = computeImpactCandidates(resultPaths);
+            // Use existing pattern intelligence for evidenceLock scoring, but keep the output payload lite.
+            const preferredPatternsForEvidence = [];
+            const patterns = intelligence.patterns || {};
+            for (const [_, data] of Object.entries(patterns)) {
+                if (data.primary) {
+                    const p = data.primary;
+                    if (p.trend === 'Rising' || p.trend === 'Stable') {
+                        preferredPatternsForEvidence.push({
+                            pattern: p.name,
+                            ...(p.canonicalExample && { example: p.canonicalExample.file })
+                        });
+                    }
+                }
+            }
+            let riskLevel = 'low';
+            if (impactCandidates.length > 10) {
+                riskLevel = 'high';
+            }
+            else if (impactCandidates.length > 3) {
+                riskLevel = 'medium';
+            }
+            editPreflight = {
+                mode: 'lite',
+                riskLevel,
+                confidence: computeIndexConfidence(),
+                evidenceLock: buildEvidenceLock({
+                    results,
+                    preferredPatterns: preferredPatternsForEvidence.slice(0, 5),
+                    relatedMemories,
+                    failureWarnings: [],
+                    patternConflicts: [],
+                    searchQualityStatus: searchQuality.status
+                })
+            };
+        }
+        catch {
+            // editPreflight is best-effort - never fail search over it
+        }
+    }
+    // Compose preflight card for edit/refactor/migrate intents
+    let preflight = undefined;
+    const preflightIntents = ['edit', 'refactor', 'migrate'];
+    if (intent && preflightIntents.includes(intent)) {
+        if (!intelligence) {
+            preflight = {
+                ready: false,
+                nextAction: 'Run a full index rebuild to generate pattern intelligence before editing.'
+            };
+        }
+        else {
+            try {
+                // --- Avoid / Prefer patterns ---
+                const avoidPatternsList = [];
+                const preferredPatternsList = [];
+                const patterns = intelligence.patterns || {};
+                for (const [category, data] of Object.entries(patterns)) {
+                    // Primary pattern = preferred if Rising or Stable
+                    if (data.primary) {
+                        const p = data.primary;
+                        if (p.trend === 'Rising' || p.trend === 'Stable') {
+                            preferredPatternsList.push({
+                                pattern: p.name,
+                                category,
+                                adoption: p.frequency,
+                                trend: p.trend,
+                                guidance: p.guidance,
+                                ...(p.canonicalExample && { example: p.canonicalExample.file })
+                            });
+                        }
+                    }
+                    // Also-detected patterns that are Declining = avoid
+                    if (data.alsoDetected) {
+                        for (const alt of data.alsoDetected) {
+                            if (alt.trend === 'Declining') {
+                                avoidPatternsList.push({
+                                    pattern: alt.name,
+                                    category,
+                                    adoption: alt.frequency,
+                                    trend: 'Declining',
+                                    guidance: alt.guidance
+                                });
+                            }
+                        }
+                    }
+                }
+                // --- Impact candidates (files importing the result files) ---
+                const resultPaths = results.map((r) => r.filePath);
+                const impactCandidates = computeImpactCandidates(resultPaths);
+                // PREF-02: Compute impact coverage (callers of result files that appear in results)
+                const callerFiles = resultPaths.flatMap((p) => {
+                    const importers = [];
+                    for (const [dep, importerList] of reverseImports) {
+                        if (dep.endsWith(p) || p.endsWith(dep)) {
+                            importers.push(...importerList);
+                        }
+                    }
+                    return importers;
+                });
+                const uniqueCallers = new Set(callerFiles);
+                const callersCovered = Array.from(uniqueCallers).filter((f) => resultPaths.some((rp) => f.endsWith(rp) || rp.endsWith(f))).length;
+                const callersTotal = uniqueCallers.size;
+                const impactCoverage = callersTotal > 0 ? { covered: callersCovered, total: callersTotal } : undefined;
+                // --- Risk level (based on circular deps + impact breadth) ---
+                //TODO: Review this risk level calculation
+                let _riskLevel = 'low';
+                let cycleCount = 0;
+                const graphDataSource = relationships?.graph || intelligence?.internalFileGraph;
+                if (graphDataSource) {
+                    try {
+                        const graph = InternalFileGraph.fromJSON(graphDataSource, ctx.rootPath);
+                        // Use directory prefixes as scope (not full file paths)
+                        // findCycles(scope) filters files by startsWith, so a full path would only match itself
+                        const scopes = new Set(resultPaths.map((rp) => {
+                            const lastSlash = rp.lastIndexOf('/');
+                            return lastSlash > 0 ? rp.substring(0, lastSlash + 1) : rp;
+                        }));
+                        for (const scope of scopes) {
+                            const cycles = graph.findCycles(scope);
+                            cycleCount += cycles.length;
+                        }
+                    }
+                    catch {
+                        // Graph reconstruction failed — skip cycle check
+                    }
+                }
+                if (cycleCount > 0 || impactCandidates.length > 10) {
+                    _riskLevel = 'high';
+                }
+                else if (impactCandidates.length > 3) {
+                    _riskLevel = 'medium';
+                }
+                // --- Golden files (exemplar code) ---
+                const goldenFiles = (intelligence.goldenFiles ?? [])
+                    .slice(0, 3)
+                    .map((g) => ({
+                    file: g.file,
+                    score: g.score
+                }));
+                // --- Confidence (index freshness) ---
+                // TODO: Review this confidence calculation
+                //const confidence = computeIndexConfidence();
+                // --- Failure memories (1.5x relevance boost) ---
+                const failureWarnings = relatedMemories
+                    .filter((m) => m.type === 'failure' && !m.stale)
+                    .map((m) => ({
+                    memory: m.memory,
+                    reason: m.reason,
+                    confidence: m.effectiveConfidence
+                }))
+                    .slice(0, 3);
+                const preferredPatternsForOutput = preferredPatternsList.slice(0, 5);
+                const avoidPatternsForOutput = avoidPatternsList.slice(0, 5);
+                // --- Pattern conflicts (split decisions within categories) ---
+                const patternConflicts = [];
+                const hasUnitTestFramework = Boolean(patterns.unitTestFramework?.primary);
+                for (const [cat, data] of Object.entries(patterns)) {
+                    if (shouldSkipLegacyTestingFrameworkCategory(cat, patterns))
+                        continue;
+                    if (!shouldIncludePatternConflictCategory(cat, queryStr))
+                        continue;
+                    if (!data.primary || !data.alsoDetected?.length)
+                        continue;
+                    const primaryFreq = parseFloat(data.primary.frequency) || 100;
+                    if (primaryFreq >= 80)
+                        continue;
+                    for (const alt of data.alsoDetected) {
+                        const altFreq = parseFloat(alt.frequency) || 0;
+                        if (altFreq >= 20) {
+                            if (isComplementaryPatternConflict(cat, data.primary.name, alt.name))
+                                continue;
+                            if (hasUnitTestFramework && cat === 'testingFramework')
+                                continue;
+                            patternConflicts.push({
+                                category: cat,
+                                primary: { name: data.primary.name, adoption: data.primary.frequency },
+                                alternative: { name: alt.name, adoption: alt.frequency }
+                            });
+                        }
+                    }
+                }
+                const evidenceLock = buildEvidenceLock({
+                    results,
+                    preferredPatterns: preferredPatternsForOutput,
+                    relatedMemories,
+                    failureWarnings,
+                    patternConflicts,
+                    searchQualityStatus: searchQuality.status,
+                    impactCoverage
+                });
+                // Build clean decision card (PREF-01 to PREF-04)
+                const decisionCard = {
+                    ready: evidenceLock.readyToEdit
+                };
+                // Add nextAction if not ready
+                if (!decisionCard.ready && evidenceLock.nextAction) {
+                    decisionCard.nextAction = evidenceLock.nextAction;
+                }
+                // Add warnings from failure memories (capped at 3)
+                if (failureWarnings.length > 0) {
+                    decisionCard.warnings = failureWarnings.slice(0, 3).map((w) => w.memory);
+                }
+                // Add patterns (do/avoid, capped at 3 each, with adoption %)
+                const doPatterns = preferredPatternsForOutput
+                    .slice(0, 3)
+                    .map((p) => `${p.pattern} — ${p.adoption ? `${p.adoption} adoption` : ''}`);
+                const avoidPatterns = avoidPatternsForOutput
+                    .slice(0, 3)
+                    .map((p) => `${p.pattern} — ${p.adoption ? `${p.adoption} adoption` : ''} (declining)`);
+                if (doPatterns.length > 0 || avoidPatterns.length > 0) {
+                    decisionCard.patterns = {
+                        ...(doPatterns.length > 0 && { do: doPatterns }),
+                        ...(avoidPatterns.length > 0 && { avoid: avoidPatterns })
+                    };
+                }
+                // Add bestExample (top 1 golden file)
+                if (goldenFiles.length > 0) {
+                    decisionCard.bestExample = `${goldenFiles[0].file}`;
+                }
+                // Add impact (coverage + top 3 files)
+                if (impactCoverage || impactCandidates.length > 0) {
+                    const impactObj = {};
+                    if (impactCoverage) {
+                        impactObj.coverage = `${impactCoverage.covered}/${impactCoverage.total} callers in results`;
+                    }
+                    if (impactCandidates.length > 0) {
+                        const top = impactCandidates.slice(0, 3);
+                        impactObj.files = top.map((candidate) => candidate.file);
+                        impactObj.details = top;
+                    }
+                    if (Object.keys(impactObj).length > 0) {
+                        decisionCard.impact = impactObj;
+                    }
+                }
+                // Add whatWouldHelp from evidenceLock
+                if (evidenceLock.whatWouldHelp && evidenceLock.whatWouldHelp.length > 0) {
+                    decisionCard.whatWouldHelp = evidenceLock.whatWouldHelp;
+                }
+                preflight = decisionCard;
+            }
+            catch {
+                // Preflight construction failed — skip preflight, don't fail the search
+            }
+        }
+    }
+    // For edit/refactor/migrate: return clean decision card.
+    // For explore or lite-only: return lightweight { ready, reason }.
+    let preflightPayload;
+    if (preflight) {
+        // preflight is already a clean decision card (DecisionCard type)
+        preflightPayload = preflight;
+    }
+    else if (editPreflight) {
+        // Lite preflight for explore intent
+        const el = editPreflight.evidenceLock;
+        preflightPayload = {
+            ready: el?.readyToEdit ?? false,
+            ...(el && !el.readyToEdit && el.nextAction && { reason: el.nextAction })
+        };
+    }
+    // Helper: Build scope header for symbol-aware chunks (SEARCH-02)
+    function buildScopeHeader(metadata) {
+        // Try symbolPath first (most reliable for AST-based symbols)
+        if (metadata?.symbolPath && Array.isArray(metadata.symbolPath)) {
+            return metadata.symbolPath.join('.');
+        }
+        // Fallback: className + functionName
+        if (metadata?.className && metadata?.functionName) {
+            return `${metadata.className}.${metadata.functionName}`;
+        }
+        // Class only
+        if (metadata?.className) {
+            return metadata.className;
+        }
+        // Function only
+        if (metadata?.functionName) {
+            return metadata.functionName;
+        }
+        // component chunk fallback (component or pipe name)
+        if (metadata?.componentName) {
+            return metadata.componentName;
+        }
+        return null;
+    }
+    function formatSnippetFallbackHeader(filePath, startLine) {
+        const rel = path.relative(ctx.rootPath, filePath).replace(/\\/g, '/');
+        const displayPath = rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? rel : path.basename(filePath);
+        return `${displayPath}:${startLine}`;
+    }
+    function enrichSnippetWithScope(snippet, metadata, filePath, startLine) {
+        if (!snippet)
+            return undefined;
+        const cleanedSnippet = snippet.replace(/^\r?\n+/, '');
+        if (cleanedSnippet.startsWith('//')) {
+            return cleanedSnippet;
+        }
+        const scopeHeader = buildScopeHeader(metadata) ?? formatSnippetFallbackHeader(filePath, startLine);
+        return `// ${scopeHeader}\n${cleanedSnippet}`;
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    status: 'success',
+                    searchQuality: {
+                        status: searchQuality.status,
+                        confidence: searchQuality.confidence,
+                        ...(searchQuality.status === 'low_confidence' &&
+                            searchQuality.nextSteps?.[0] && {
+                            hint: searchQuality.nextSteps[0]
+                        })
+                    },
+                    ...(preflightPayload && { preflight: preflightPayload }),
+                    results: results.map((r) => {
+                        const relationshipsAndHints = buildRelationshipHints(r);
+                        const enrichedSnippet = includeSnippets
+                            ? enrichSnippetWithScope(r.snippet, r.metadata, r.filePath, r.startLine)
+                            : undefined;
+                        return {
+                            file: `${r.filePath}:${r.startLine}-${r.endLine}`,
+                            summary: r.summary,
+                            score: Math.round(r.score * 100) / 100,
+                            ...(r.componentType &&
+                                r.layer &&
+                                r.layer !== 'unknown' && { type: `${r.componentType}:${r.layer}` }),
+                            ...(r.trend && r.trend !== 'Stable' && { trend: r.trend }),
+                            ...(r.patternWarning && { patternWarning: r.patternWarning }),
+                            ...(relationshipsAndHints.relationships && {
+                                relationships: relationshipsAndHints.relationships
+                            }),
+                            ...(relationshipsAndHints.hints && { hints: relationshipsAndHints.hints }),
+                            ...(enrichedSnippet && { snippet: enrichedSnippet })
+                        };
+                    }),
+                    totalResults: results.length,
+                    ...(relatedMemories.length > 0 && {
+                        relatedMemories: relatedMemories
+                            .slice(0, 3)
+                            .map((m) => `${m.memory} (${m.effectiveConfidence})`)
+                    })
+                }, null, 2)
+            }
+        ]
+    };
+}
+//# sourceMappingURL=search-codebase.js.map