Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
/**
* Vorschlaege aus dem, was ohnehin schon geladen ist.
*
* ## Warum es sie gibt
*
* Nutzerbefund vom 2026-08-29: die Suchvorschlaege erscheinen zu langsam. Der
* Weg war bis dahin: tippen, 200 ms warten, ein Wort je Anfrage an den Server,
* dann die erste Zeile. In dieser Zeit ist der Bildschirm leer, obwohl der
* Browser die Antwort auf einen guten Teil der Frage schon im Speicher hat.
*
* Zwei Quellen liegen dort und kosten keinen Serverweg:
*
* 1. **Die Knoten des Layouts.** Die Galaxie laedt sie beim Start; jeder traegt
* Name, qualifizierten Namen, Datei und Deklarationszeile.
* 2. **Die Dateien des Baums.** Der Explorer laedt sie beim Start ebenfalls,
* und ein Leser, der `userService` tippt, meint oft genau die Datei.
*
* ## Was diese Vorschlaege sind und was nicht
*
* Sie sind **vorlaeufig** und sagen das auch: die Zeile traegt eine Marke, und
* sobald die Antwort des Index da ist, steht dort das Ergebnis der Suche. Ein
* lokaler Vorschlag ist keine Behauptung ueber den Index, sondern eine Aussage
* ueber das, was dieses Fenster schon weiss. Er ist trotzdem nie eine
* Attrappe: jede Zeile fuehrt an eine Stelle, die dieses Fenster oeffnen kann.
*
* Gerankt wird mit **derselben** Funktion wie die Antwort des Servers
* (`rankHits`). Eine eigene Ordnung fuer die vorlaeufigen Zeilen waere die
* teuerste Art, den Sprung zu bauen, den dieser Zyklus abschaffen soll: die
* Liste wuerde beim Eintreffen der Antwort nicht ersetzt, sondern umsortiert.
*
* ## Die eine Abweichung, und warum sie eine ist
*
* `isNavigable` (semantic-search.ts) wirft Treffer weg, die nach ihrer eigenen
* Datei heissen, und Treffer mit der Art `module`. Der Grund dort ist richtig:
* die Suchantwort des Servers enthaelt Datei- und Modulzeilen als Dubletten der
* Symbolzeilen, und ein Modul hat keine Deklaration, zu der man springen
* koennte. Hier ist die Lage eine andere: der Baum liefert Dateien, keine
* Dubletten, und diese Oberflaeche oeffnet eine Datei mit einem Klick, genau so
* wie der Explorer es tut. Eine Datei bekommt deshalb den Stamm ihres Namens
* (`userService` fuer `src/services/userService.ts`) und die Art `unknown`: der
* Index hat sie nicht als Symbol eingeordnet, und etwas anderes zu behaupten
* waere eine erfundene Symbolart.
*/
import type { CodeAtlasSymbolKind } from '../core/focus-protocol';
import type { SymbolSearchHit } from '../core/intelligence-provider';
import type { RankedHit } from './semantic-search';
import { rankHits } from './semantic-search';
import { fileQueryPath } from './path-query';
/** Wie viele Sofort-Vorschlaege hoechstens gerechnet werden. */
export const MAX_LOCAL_SUGGESTIONS = 10;
/** Was der Browser schon geladen hat, in der Form, die diese Datei braucht. */
export interface LocalIndex {
/** Symbole aus dem Layout der Galaxie. */
symbols: readonly SymbolSearchHit[];
/** Dateipfade aus dem Baum, workspace-relativ. */
files: readonly string[];
}
/** Nichts geladen. Als benannte Konstante, damit sie eine stabile Referenz ist. */
export const EMPTY_LOCAL_INDEX: LocalIndex = { symbols: [], files: [] };
/** Settle an index reply while retaining the provenance of displayed rows. */
export function settledSearchHits(indexed: RankedHit[], loaded: RankedHit[]): {
hits: RankedHit[];
source: 'index' | 'loaded';
} {
if (loaded[0]?.pathMatch === 'file' && indexed[0]?.pathMatch !== 'file') {
return { hits: loaded, source: 'loaded' };
}
if (indexed.length === 0 && loaded.length > 0) {
return { hits: loaded, source: 'loaded' };
}
return { hits: indexed, source: 'index' };
}
/** Die Art, die eine Datei aus dem Baum bekommt. Siehe Kopf, letzter Abschnitt. */
export const FILE_CANDIDATE_KIND: CodeAtlasSymbolKind = 'unknown';
/**
* Der Name, unter dem eine Datei als Kandidat auftritt: ihr Basisname ohne die
* letzte Endung.
*
* Ohne Endung, weil ein Leser `userService` tippt und nicht `userService.ts`,
* und weil ein Kandidat, der genau so heisst wie das Ende seines Pfades, von
* `isNavigable` als Dublette verworfen wuerde.
*/
export function fileStem(path: string): string {
const base = path.split('/').pop() ?? '';
const dot = base.lastIndexOf('.');
return dot > 0 ? base.slice(0, dot) : base;
}
/** Die Kandidaten, die die Dateien des Baums beitragen. */
export function fileCandidates(files: readonly string[]): SymbolSearchHit[] {
const seen = new Set<string>();
const out: SymbolSearchHit[] = [];
for (const path of files) {
const name = fileStem(path);
if (name.length === 0 || seen.has(path)) {
continue;
}
seen.add(path);
out.push({ name, kind: FILE_CANDIDATE_KIND, filePath: path });
}
return out;
}
/**
* Alles, was der Browser als Kandidat hergibt, ungerankt.
*
* Getrennt von {@link localSuggestions}, weil die Kommandozeile die Kandidaten
* mit denen des Praefix-Caches in EINEN Rang wirft: zweimal zu ranken und dann
* zwei Listen zu mischen waere eine zweite Ordnung neben der einen, die dieses
* Produkt hat.
*/
export function localCandidates(index: LocalIndex): SymbolSearchHit[] {
return [...index.symbols, ...fileCandidates(index.files)];
}
/** Rank the immediate local/cache pool without substituting a different file.
* A full path may be typed before the corresponding tree branch has loaded.
* Empty provisional results let the UI show its pending index lookup, so Enter
* cannot open an unrelated token match while that exact request is in flight.
*/
export function rankLocalCandidates(
candidates: readonly SymbolSearchHit[], query: string,
fanInOf: (hit: SymbolSearchHit) => number = () => 0,
limit: number = MAX_LOCAL_SUGGESTIONS,
): RankedHit[] {
const path = fileQueryPath(query);
const eligible = path ? candidates.filter(hit => hit.filePath === path) : candidates;
return rankHits(eligible, query, fanInOf).slice(0, limit);
}
/**
* Die Sofort-Vorschlaege zu einer Anfrage, ohne einen einzigen Serverweg.
*
* Leer heisst hier wirklich leer: nichts Geladenes beantwortet dieses Wort. Die
* Kommandozeile zeigt dann, dass gesucht wird, statt eine Zeile zu erfinden.
*/
export function localSuggestions(
index: LocalIndex,
query: string,
fanInOf: (hit: SymbolSearchHit) => number = () => 0,
limit: number = MAX_LOCAL_SUGGESTIONS,
): RankedHit[] {
if (index.symbols.length === 0 && index.files.length === 0) {
return [];
}
return rankLocalCandidates(localCandidates(index), query, fanInOf, limit);
}