codebase-context 1.7.0 → 1.8.0

package/dist/tools/search-codebase.js

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 import { promises as fs } from 'fs';
 import path from 'path';
 import { CodebaseSearcher } from '../core/search.js';
@@ -115,7 +114,7 @@ export async function handle(args, ctx) {
     }
     const searcher = new CodebaseSearcher(ctx.rootPath);
     let results;
-    const searchProfile = intent && ['explore', 'edit', 'refactor', 'migrate'].includes(intent) ? intent : 'explore';
+    const searchProfile = (intent && ['explore', 'edit', 'refactor', 'migrate'].includes(intent) ? intent : 'explore');
     try {
         results = await searcher.search(queryStr, limit || 5, filters, {
             profile: searchProfile
@@ -180,7 +179,10 @@ export async function handle(args, ctx) {
     let intelligence = null;
     try {
         const intelligenceContent = await fs.readFile(ctx.paths.intelligence, 'utf-8');
-        intelligence = JSON.parse(intelligenceContent);
+        const parsed = JSON.parse(intelligenceContent);
+        if (typeof parsed === 'object' && parsed !== null) {
+            intelligence = parsed;
+        }
     }
     catch {
         /* graceful degradation — intelligence file may not exist yet */
@@ -190,7 +192,10 @@ export async function handle(args, ctx) {
     try {
         const relationshipsPath = path.join(path.dirname(ctx.paths.intelligence), RELATIONSHIPS_FILENAME);
         const relationshipsContent = await fs.readFile(relationshipsPath, 'utf-8');
-        relationships = JSON.parse(relationshipsContent);
+        const parsed = JSON.parse(relationshipsContent);
+        if (typeof parsed === 'object' && parsed !== null) {
+            relationships = parsed;
+        }
     }
     catch {
         /* graceful degradation — relationships sidecar may not exist yet */
@@ -205,6 +210,29 @@ export async function handle(args, ctx) {
         }
         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) {
@@ -219,20 +247,78 @@ export async function handle(args, ctx) {
         }
         return confidence;
     }
-    // Cheap impact breadth estimate from the import graph (used for risk assessment).
+    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 impactCandidates = [];
         const allImports = getImportsGraph();
         if (!allImports)
-            return impactCandidates;
+            return [];
+        const importDetails = getImportDetailsGraph();
+        const reverseImportsLocal = new Map();
         for (const [file, deps] of Object.entries(allImports)) {
-            if (deps.some((dep) => resultPaths.some((rp) => dep.endsWith(rp) || rp.endsWith(dep)))) {
-                if (!resultPaths.some((rp) => file.endsWith(rp) || rp.endsWith(file))) {
-                    impactCandidates.push(file);
+            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 impactCandidates;
+        return Array.from(candidates.values()).slice(0, 20);
     }
     // Build reverse import map from relationships sidecar (preferred) or intelligence graph
     const reverseImports = new Map();
@@ -304,7 +390,7 @@ export async function handle(args, ctx) {
         }
         return output;
     }
-    const searchQuality = assessSearchQuality(query, results);
+    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')) {
@@ -353,193 +439,206 @@ export async function handle(args, ctx) {
     // Compose preflight card for edit/refactor/migrate intents
     let preflight = undefined;
     const preflightIntents = ['edit', 'refactor', 'migrate'];
-    if (intent && preflightIntents.includes(intent) && intelligence) {
-        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,
+    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: alt.frequency,
-                                trend: 'Declining',
-                                guidance: alt.guidance
+                                adoption: p.frequency,
+                                trend: p.trend,
+                                guidance: p.guidance,
+                                ...(p.canonicalExample && { example: p.canonicalExample.file })
                             });
                         }
                     }
-                }
-            }
-            // --- 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);
+                    // 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
+                                });
+                            }
+                        }
                     }
                 }
-                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;
+                // --- 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
                     }
                 }
-                catch {
-                    // Graph reconstruction failed — skip cycle check
+                if (cycleCount > 0 || impactCandidates.length > 10) {
+                    _riskLevel = 'high';
                 }
-            }
-            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, query))
-                    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 }
-                        });
+                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
-            });
-            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 })
+                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 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`;
+                // Add nextAction if not ready
+                if (!decisionCard.ready && evidenceLock.nextAction) {
+                    decisionCard.nextAction = evidenceLock.nextAction;
                 }
-                if (impactCandidates.length > 0) {
-                    impactObj.files = impactCandidates.slice(0, 3);
+                // Add warnings from failure memories (capped at 3)
+                if (failureWarnings.length > 0) {
+                    decisionCard.warnings = failureWarnings.slice(0, 3).map((w) => w.memory);
                 }
-                if (Object.keys(impactObj).length > 0) {
-                    decisionCard.impact = impactObj;
+                // 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;
             }
-            // Add whatWouldHelp from evidenceLock
-            if (evidenceLock.whatWouldHelp && evidenceLock.whatWouldHelp.length > 0) {
-                decisionCard.whatWouldHelp = evidenceLock.whatWouldHelp;
+            catch {
+                // Preflight construction failed — skip preflight, don't fail the search
             }
-            preflight = decisionCard;
-        }
-        catch {
-            // Preflight construction failed — skip preflight, don't fail the search
         }
     }
     // For edit/refactor/migrate: return clean decision card.
@@ -581,14 +680,20 @@ export async function handle(args, ctx) {
         }
         return null;
     }
-    function enrichSnippetWithScope(snippet, metadata) {
+    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 scopeHeader = buildScopeHeader(metadata);
-        if (scopeHeader) {
-            return `// ${scopeHeader}\n${snippet}`;
+        const cleanedSnippet = snippet.replace(/^\r?\n+/, '');
+        if (cleanedSnippet.startsWith('//')) {
+            return cleanedSnippet;
         }
-        return snippet;
+        const scopeHeader = buildScopeHeader(metadata) ?? formatSnippetFallbackHeader(filePath, startLine);
+        return `// ${scopeHeader}\n${cleanedSnippet}`;
     }
     return {
         content: [
@@ -608,13 +713,15 @@ export async function handle(args, ctx) {
                     results: results.map((r) => {
                         const relationshipsAndHints = buildRelationshipHints(r);
                         const enrichedSnippet = includeSnippets
-                            ? enrichSnippetWithScope(r.snippet, r.metadata)
+                            ? 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 && { type: `${r.componentType}:${r.layer}` }),
+                            ...(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 && {