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
/**
* Der Datei-Baum, wie ihn der Explorer zeigt: die VEREINIGUNG aus dem Graphen
* und den Coverage-Listen des Servers.
*
* `/api/tree?project=X&path=Y` antwortet mit genau einer Ebene: den direkten
* Kindern von Y, jedes mit `name`, `path`, `kind` ("dir" oder "file") und den
* Zahlen `symbols` und `files`. Der Baum kommt also stueckweise, eine Ebene je
* Anfrage, und dieses Modul haelt die Ebenen zusammen und rechnet aus, welche
* Zeilen davon gerade sichtbar sind.
*
* **Der Graph ist nur eine der Quellen.** Bis W4c war er die einzige, und damit
* zeigte der Explorer genau die Dateien, aus denen Symbole geworden sind. Eine
* Datei, die der Indexer uebersprungen hat, war unsichtbar, und Unsichtbarkeit
* ist in einem Explorer die Behauptung, es gebe sie nicht. Seit W4d stehen
* daneben zwei weitere Quellen, beide vom selben Server:
*
* - `index_status` traegt eine Coverage-Beilage: `parse_partial` (indiziert,
* aber mit Parse-Fehlern), `skipped` (gar nicht indiziert, mit Grund) und
* `not_indexed` (nach Absicht ausgeschlossen, Dateien UND Verzeichnisse).
* Jede der drei Listen nennt ihre eigene Zahl und ihr eigenes `truncated`.
* - `check_index_coverage` mit `scopes: ["."]` listet die Eintraege des
* Coverage-Stores selbst, paginiert ueber `scope_offset`, und deckt damit
* auch Faelle, die `index_status` kappt.
*
* Der Coverage-Store ist eine eigene Tabelle NEBEN dem Graphen (mcp.c: "coverage
* is metadata ABOUT the graph, stored outside it"). Darum ist die Vereinigung
* keine Bequemlichkeit, sondern die einzige Form, in der der Explorer beide
* Wahrheiten gleichzeitig zeigen kann: was indiziert wurde, und was der Index
* angefasst und liegengelassen hat.
*
* Was danach immer noch fehlt, wird nicht verschwiegen: eine Datei, die die
* Discovery nie gesehen hat, steht in keiner der drei Quellen. Die Legende im
* Explorer-Fuss sagt das mit eigenen Worten, statt den Baum vollstaendig
* aussehen zu lassen.
*
* Zwei Eigenheiten des Graph-Baums bleiben, an einem laufenden Server
* abgelesen und hier ausdruecklich behandelt, statt sie im Explorer als
* Geisterzeilen zu zeigen:
*
* 1. **Ordner erscheinen doppelt.** Der Server gruppiert alle Knoten nach
* `file_path`. Ein Folder-Knoten traegt als `file_path` den Ordnerpfad
* selbst, also faellt zu `src` ein zweites Kind an, diesmal mit
* `kind: "file"`. Zwei Kinder mit demselben Pfad sind aber ein Ding: der
* Ordner. Sie werden zusammengelegt, der Ordner gewinnt, und wie oft das
* passiert ist, steht in `foldedDuplicates`.
* 2. **`{}` ist kein Pfad.** Die Project- und Branch-Knoten des Projekts
* tragen `{}` als `file_path`, und der Server macht daraus brav ein Kind
* namens `{}`. Eine Datei dieses Namens gibt es nicht. Solche Kinder fallen
* weg und werden in `droppedNonPaths` gezaehlt, damit der Explorer sagen
* kann, dass er etwas weggelassen hat, statt es zu verschweigen.
*
* Beides ist ein Serverbefund und gehoert auf die Ask-Liste, nicht in eine
* stille Reparatur: gezaehlt wird, was wegfaellt.
*/
/**
* Wie weit der Index eine Datei erfasst hat.
*
* Die fuenf Werte sind genau die Klassen, die der Server meldet, und keine
* mehr: `indexed` ist die Abwesenheit eines Befundes, die anderen vier kommen
* aus dem `kind` einer Coverage-Zeile. Ein sechster Wert waere ein Status, den
* niemand gemeldet hat.
*/
export type CoverageState = 'indexed' | 'partial' | 'skipped' | 'not-indexed' | 'ignored';
/**
* Die Stufen von "ganz da" nach "am unerklaertesten weg".
*
* Die Reihenfolge ist eine Aussage und keine Geschmacksfrage. `partial` steht
* vorn, weil die Datei im Graphen steht und nur Teile fehlen. Danach kommen die
* beiden erklaerten Abwesenheiten: `ignored` (der Coverage-Store fuehrt sie als
* ignoriert) und `not-indexed` (nach Absicht ausgeschlossen, mit Regel als
* Grund). Ganz hinten steht `skipped`, denn dort hat der Indexer die Datei
* angefasst und aufgegeben: eine unerklaerte Luecke ist fuer einen Leser
* schlimmer als eine erklaerte.
*/
export const COVERAGE_ORDER: readonly CoverageState[] = [
'indexed',
'partial',
'ignored',
'not-indexed',
'skipped',
];
/** Der Rang einer Stufe. Groesser heisst schlechter erfasst. */
export function coverageRank(state: CoverageState): number {
const index = COVERAGE_ORDER.indexOf(state);
return index === -1 ? 0 : index;
}
/** Die schlechtere der beiden Stufen. Der Konfliktloeser des Joins. */
export function worstCoverage(left: CoverageState, right: CoverageState): CoverageState {
return coverageRank(right) > coverageRank(left) ? right : left;
}
/**
* Das `kind` einer Coverage-Zeile als Stufe.
*
* Der Server schreibt `parse_partial`, `not_indexed_dir`, `not_indexed_file`
* und ansonsten den Namen der Phase, in der er aufgegeben hat (mcp.c,
* add_coverage_report: alles, was keiner der drei Namen ist, landet unter
* `skipped`). Genau diese Zuordnung steht hier, damit die Oberflaeche keine
* eigene erfindet.
*/
export function coverageStateForKind(kind: string): CoverageState {
if (kind === 'parse_partial') {
return 'partial';
}
if (kind.startsWith('not_indexed')) {
return 'not-indexed';
}
if (kind.startsWith('ignored') || kind.startsWith('gitignored')) {
return 'ignored';
}
return 'skipped';
}
/** Ein Kind einer Baum-Ebene, so wie der Explorer es zeigt. */
export interface TreeChild {
name: string;
path: string;
kind: 'dir' | 'file';
/** Symbole, die der Graph unter diesem Kind fuehrt. */
symbols: number;
/** Dateien, die der Graph unter diesem Kind fuehrt. */
files: number;
/** Dateien, die der Index unter diesem Kind ausgelassen hat, wenn er es sagt. */
missed?: number;
/**
* Die Stufe dieser Zeile. Bei Ordnern die schlechteste ihres Teilbaums.
*
* Fehlt sie, ist noch nichts gejoint worden. Das ist ausdruecklich nicht
* dasselbe wie `indexed`: solange die Coverage-Antwort nicht da ist, hat
* niemand etwas ueber diese Datei gesagt.
*/
coverage?: CoverageState;
/** Der Grund des Servers, soweit er einen genannt hat. */
coverageReason?: string;
/** Die Quellen, die diesen Pfad genannt haben. Fuer die ehrliche Herkunft. */
coverageSources?: string[];
}
/** Eine Ebene des Baums, plus was auf dem Weg dorthin weggefallen ist. */
export interface TreeLevel {
path: string;
files: number;
symbols: number;
children: TreeChild[];
/** Wie viele Kinder mit einem Ordner desselben Pfades zusammengelegt wurden. */
foldedDuplicates: number;
/** Wie viele Kinder keinen Pfad benannt haben und darum weggefallen sind. */
droppedNonPaths: number;
/**
* True, wenn diese Ebene nicht von `/api/tree` kam, sondern beim Join
* entstanden ist, weil ein Coverage-Eintrag darunter liegt.
*
* Der Explorer braucht das, um ein fehlgeschlagenes Nachladen einer solchen
* Ebene nicht als Baumfehler zu melden: ein Ordner, den nur die
* Coverage-Listen kennen, hat im Graphen keine Ebene, und das ist der
* erwartete Fall und kein Ausfall.
*/
synthetic?: boolean;
}
/** Eine sichtbare Zeile des Explorers. */
export interface TreeRow extends TreeChild {
/** Verschachtelungstiefe, 0 fuer die oberste Ebene. */
depth: number;
/** Nur fuer Ordner: ob die Ebene darunter gerade gezeigt wird. */
expanded: boolean;
/** Nur fuer Ordner: ob die Ebene darunter schon geladen ist. */
loaded: boolean;
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value);
}
function asNumber(value: unknown): number {
const parsed = typeof value === 'number' ? value : Number(value);
return Number.isFinite(parsed) ? parsed : 0;
}
/**
* Ob ein Kind einen Pfad benennt.
*
* Die Pruefung ist absichtlich schmal: sie kennt genau die eine Form, die der
* Server statt eines Pfades schickt (`{}`, das leere JSON-Objekt der
* Project- und Branch-Knoten), und sonst nichts. Eine breitere Heuristik wuerde
* frueher oder spaeter eine echte Datei verschlucken, und eine verschluckte
* Datei ist schlimmer als eine haessliche Zeile.
*/
export function namesAPath(child: { name: string; path: string }): boolean {
if (child.name.length === 0 || child.path.length === 0) {
return false;
}
return child.name !== '{}' && child.path !== '{}';
}
/**
* Anzeigeordnung: Ordner zuerst, dann Dateien, beides alphabetisch.
*
* Der Server sortiert nach Symbolzahl. Das ist eine sinnvolle Ordnung fuer eine
* Auswertung und eine schlechte fuer einen Explorer, in dem man eine Datei
* *suchen* will. Die Ordnung hier ist stabil und haengt an nichts, was sich
* beim naechsten Indexlauf verschiebt.
*/
export function compareChildren(left: TreeChild, right: TreeChild): number {
if (left.kind !== right.kind) {
return left.kind === 'dir' ? -1 : 1;
}
return left.name.localeCompare(right.name, 'en');
}
/** Eine Antwort von `/api/tree` lesen: falten, aussortieren, sortieren. */
export function readTreeLevel(payload: unknown): TreeLevel {
const raw = isRecord(payload) ? payload : {};
const rawChildren = Array.isArray(raw['children']) ? raw['children'] : [];
const byPath = new Map<string, TreeChild>();
let foldedDuplicates = 0;
let droppedNonPaths = 0;
for (const entry of rawChildren) {
if (!isRecord(entry)) {
continue;
}
const name = typeof entry['name'] === 'string' ? entry['name'] : '';
const path = typeof entry['path'] === 'string' ? entry['path'] : '';
if (!namesAPath({ name, path })) {
droppedNonPaths += 1;
continue;
}
const child: TreeChild = {
name,
path,
kind: entry['kind'] === 'dir' ? 'dir' : 'file',
symbols: asNumber(entry['symbols']),
files: asNumber(entry['files']),
};
const missed = asNumber(entry['missed']);
if (missed > 0) {
child.missed = missed;
}
const existing = byPath.get(path);
if (existing === undefined) {
byPath.set(path, child);
continue;
}
// Derselbe Pfad zweimal: der Ordner ist die Wahrheit, die Zahlen des
// Ordners auch. Der Folder-Knoten steuert nur sich selbst bei.
foldedDuplicates += 1;
if (existing.kind === 'file' && child.kind === 'dir') {
byPath.set(path, child);
}
}
return {
path: typeof raw['path'] === 'string' ? raw['path'] : '',
files: asNumber(raw['files']),
symbols: asNumber(raw['symbols']),
children: [...byPath.values()].sort(compareChildren),
foldedDuplicates,
droppedNonPaths,
};
}
/** Der Pfad des Ordners ueber diesem Pfad. Leer heisst Projektwurzel. */
export function parentPath(path: string): string {
const slash = path.lastIndexOf('/');
return slash === -1 ? '' : path.slice(0, slash);
}
/**
* Die sichtbaren Zeilen: die Wurzel-Ebene, und unter jedem aufgeklappten
* Ordner dessen geladene Ebene.
*
* Ein aufgeklappter Ordner ohne geladene Ebene erzeugt keine Zeilen und keinen
* Platzhalter. Er traegt `loaded: false`, und der Explorer zeigt das am
* Pfeil-Zeichen, statt eine leere Ebene als "hier ist nichts" auszugeben.
*/
export function flattenTree(
levels: ReadonlyMap<string, TreeLevel>,
expanded: ReadonlySet<string>,
rootPath = '',
): TreeRow[] {
const rows: TreeRow[] = [];
const walk = (path: string, depth: number, seen: Set<string>): void => {
const level = levels.get(path);
if (level === undefined || seen.has(path)) {
return;
}
seen.add(path);
for (const child of level.children) {
const isExpanded = child.kind === 'dir' && expanded.has(child.path);
rows.push({
...child,
depth,
expanded: isExpanded,
loaded: child.kind === 'dir' ? levels.has(child.path) : true,
});
if (isExpanded) {
walk(child.path, depth + 1, seen);
}
}
};
walk(rootPath, 0, new Set());
return rows;
}
/** Alle Ordnerpfade einer Ebene, in Anzeigeordnung. */
export function directoryPaths(level: TreeLevel): string[] {
return level.children.filter((child) => child.kind === 'dir').map((child) => child.path);
}
/** Was eine Taste im Explorer bedeutet. */
export type TreeIntent = 'up' | 'down' | 'open' | 'expand' | 'collapse' | 'toParent' | 'none';
/**
* Die Taste, uebersetzt in eine Absicht, mit Blick auf die Zeile unter dem
* Cursor.
*
* Rechts auf einem zugeklappten Ordner klappt auf, auf einem aufgeklappten geht
* es in die erste Zeile darunter, also einfach nach unten. Links auf einem
* aufgeklappten Ordner klappt zu, sonst springt es zum Elternordner. Das ist
* das Verhalten, das jeder Baum in jeder IDE hat, und es steht hier als reine
* Funktion, damit es ohne DOM pruefbar ist.
*/
export function treeIntent(key: string, row: TreeRow | undefined): TreeIntent {
switch (key) {
case 'ArrowDown':
return 'down';
case 'ArrowUp':
return 'up';
case 'ArrowRight':
if (row === undefined || row.kind !== 'dir') {
return 'none';
}
return row.expanded ? 'down' : 'expand';
case 'ArrowLeft':
if (row !== undefined && row.kind === 'dir' && row.expanded) {
return 'collapse';
}
return 'toParent';
case 'Enter':
case ' ':
if (row === undefined) {
return 'none';
}
if (row.kind === 'file') {
return 'open';
}
return row.expanded ? 'collapse' : 'expand';
default:
return 'none';
}
}
/** Der Cursor nach einem Schritt, an den Enden festgehalten statt umgebrochen. */
export function moveCursor(rowCount: number, cursor: number, delta: number): number {
if (rowCount <= 0) {
return 0;
}
const next = cursor + delta;
if (next < 0) {
return 0;
}
if (next >= rowCount) {
return rowCount - 1;
}
return next;
}
// ------------------------------------------------- Die Coverage-Quellen -----
/**
* Ein Pfad, wie ihn beide Quellen schreiben sollten, und manchmal nicht tun.
*
* Der Graph liefert `src/services/userService.ts`, der Coverage-Store denselben
* Pfad, und beide gelegentlich mit einem fuehrenden `./`. Ohne diese eine
* Stelle waeren `./a.ts` und `a.ts` zwei Dateien, und der Join legte zwei
* Zeilen fuer dieselbe Datei an.
*/
export function normalizeCoveragePath(path: string): string {
let value = path.replace(/\\/g, '/').trim();
while (value.startsWith('./')) {
value = value.slice(2);
}
while (value.startsWith('/')) {
value = value.slice(1);
}
while (value.endsWith('/')) {
value = value.slice(0, -1);
}
return value;
}
/** Ein Eintrag der `parse_partial`-Liste: Pfad plus die gemeldeten Zeilenbereiche. */
export interface PartialFileEntry {
path: string;
/** Die Zeilenbereiche, in denen Konstrukte fehlen koennen. Roh, wie gemeldet. */
errorRanges: string;
}
/** Ein Eintrag der `skipped`-Liste: Pfad, Grund und die Phase des Aufgebens. */
export interface SkippedFileEntry {
path: string;
reason: string;
phase: string;
}
/** Ein Eintrag der `not_indexed.files`-Liste: Pfad und die Regel, die ihn ausschliesst. */
export interface NotIndexedFileEntry {
path: string;
reason: string;
}
/** Die Coverage-Beilage von `index_status`, so wie der Server sie schreibt. */
export interface IndexStatusCoverage {
/** The index generation whose summary counts were read, when reported. */
generation?: string;
parsePartial: PartialFileEntry[];
parsePartialCount: number;
parsePartialTruncated: boolean;
skipped: SkippedFileEntry[];
skippedCount: number;
skippedTruncated: boolean;
notIndexedDirs: string[];
notIndexedDirsCount: number;
notIndexedFiles: NotIndexedFileEntry[];
notIndexedFilesCount: number;
notIndexedTruncated: boolean;
/** Der Satz, den der Server selbst unter die Listen schreibt. Leer, wenn keiner. */
note: string;
}
function coverageString(value: unknown): string {
return typeof value === 'string' ? value : '';
}
function coverageArray(value: unknown): unknown[] {
return Array.isArray(value) ? value : [];
}
/**
* Die Coverage-Beilage aus einer rohen `index_status`-Antwort lesen.
*
* Nachsichtig gegen alles, was fehlt, und streng gegen das, was behauptet wird:
* eine Antwort ohne die Beilage ergibt leere Listen mit Zahl null, nicht die
* Behauptung, es gebe keine Luecken. Der Unterschied steht in der Oberflaeche:
* dort ist "keine Liste" ein anderer Satz als "leere Liste".
*/
export function readIndexStatusCoverage(payload: unknown): IndexStatusCoverage {
const raw = isRecord(payload) ? payload : {};
const partial = isRecord(raw['parse_partial']) ? raw['parse_partial'] : {};
const skipped = isRecord(raw['skipped']) ? raw['skipped'] : {};
const notIndexed = isRecord(raw['not_indexed']) ? raw['not_indexed'] : {};
const partialFiles: PartialFileEntry[] = [];
for (const entry of coverageArray(partial['files'])) {
if (!isRecord(entry)) {
continue;
}
const path = normalizeCoveragePath(coverageString(entry['path']));
if (path.length > 0) {
partialFiles.push({ path, errorRanges: coverageString(entry['error_ranges']) });
}
}
const skippedFiles: SkippedFileEntry[] = [];
for (const entry of coverageArray(skipped['files'])) {
if (!isRecord(entry)) {
continue;
}
const path = normalizeCoveragePath(coverageString(entry['path']));
if (path.length > 0) {
skippedFiles.push({
path,
reason: coverageString(entry['reason']),
phase: coverageString(entry['phase']),
});
}
}
const notIndexedDirs: string[] = [];
for (const entry of coverageArray(notIndexed['dirs'])) {
const path = normalizeCoveragePath(coverageString(entry));
if (path.length > 0) {
notIndexedDirs.push(path);
}
}
const notIndexedFiles: NotIndexedFileEntry[] = [];
for (const entry of coverageArray(notIndexed['files'])) {
if (!isRecord(entry)) {
continue;
}
const path = normalizeCoveragePath(coverageString(entry['path']));
if (path.length > 0) {
notIndexedFiles.push({ path, reason: coverageString(entry['reason']) });
}
}
return {
...(coverageString(raw['indexed_at']) ? { generation: coverageString(raw['indexed_at']) } : {}),
parsePartial: partialFiles,
parsePartialCount: asNumber(partial['count']),
parsePartialTruncated: partial['truncated'] === true,
skipped: skippedFiles,
skippedCount: asNumber(skipped['count']),
skippedTruncated: skipped['truncated'] === true,
notIndexedDirs,
notIndexedDirsCount: asNumber(notIndexed['dirs_count']),
notIndexedFiles,
notIndexedFilesCount: asNumber(notIndexed['files_count']),
notIndexedTruncated: notIndexed['truncated'] === true,
note: coverageString(raw['coverage_note']),
};
}
/** Eine Zeile des Coverage-Stores, wie `check_index_coverage` sie ausgibt. */
export interface CoverageRow {
path: string;
kind: string;
detail: string;
/** Nur bei einer Pfad-Abfrage: ob die Zeile den Pfad selbst oder einen Vorfahren meint. */
match?: string;
}
/** Ein abgefragter Scope, mit seiner Seite und der Ansage, ob noch mehr kommt. */
export interface CoverageScope {
requestedScope: string;
scope: string;
status: string;
total: number;
hasMore: boolean;
nextOffset?: number;
entries: CoverageRow[];
}
/** Die Antwort zu genau einem abgefragten Pfad. */
export interface CoveragePathAnswer {
requestedPath: string;
path: string;
status: string;
freshness: string;
recommendedAction: string;
coverage: CoverageRow[];
}
/**
* Die Metadaten des Coverage-Stores.
*
* `ignoredFilesStored` und `ignoredFilesTotal` sind die einzige Stelle, an der
* der Server ueberhaupt etwas ueber ignorierte Dateien sagt, ohne sie zu
* nennen. Sie werden mitgelesen, weil "der Store kennt N ignorierte Dateien,
* nennt aber keine" ein anderer Befund ist als "der Store kennt keine".
*/
export interface CoverageMetadata {
generation: string;
indexMode: string;
recordedAt: string;
recordingStatus: string;
ignoredFilesStored: number;
ignoredFilesTotal: number;
hashRecordsComplete: boolean;
coverageVersion: number;
generationMatches: boolean;
}
/** Eine gelesene `check_index_coverage`-Antwort. */
export interface CoverageAnswer {
project: string;
metadata: CoverageMetadata;
paths: CoveragePathAnswer[];
scopes: CoverageScope[];
caveat: string;
}
function readCoverageRows(value: unknown): CoverageRow[] {
const rows: CoverageRow[] = [];
for (const entry of coverageArray(value)) {
if (!isRecord(entry)) {
continue;
}
const path = normalizeCoveragePath(coverageString(entry['path']));
if (path.length === 0) {
continue;
}
const row: CoverageRow = {
path,
kind: coverageString(entry['kind']),
detail: coverageString(entry['detail']),
};
// The current MCP encoder replaces parse_partial's stored detail with
// structured ranges. Preserve that source evidence in the shared join.
if (row.kind === 'parse_partial' && !row.detail) {
const ranges = coverageArray(entry['ranges']).flatMap((range) => {
if (!isRecord(range)) return [];
const start = range['start'];
const end = range['end'];
return typeof start === 'number' && typeof end === 'number'
&& Number.isSafeInteger(start) && Number.isSafeInteger(end)
&& start > 0 && end >= start ? [`${start}-${end}`] : [];
});
if (ranges.length > 0) row.detail = `Source lines: ${ranges.join(', ')}`;
}
const match = coverageString(entry['match']);
if (match.length > 0) {
row.match = match;
}
rows.push(row);
}
return rows;
}
/** Eine rohe `check_index_coverage`-Antwort lesen. */
export function readCoverageAnswer(payload: unknown): CoverageAnswer {
const raw = isRecord(payload) ? payload : {};
const meta = isRecord(raw['metadata']) ? raw['metadata'] : {};
const paths: CoveragePathAnswer[] = [];
for (const entry of coverageArray(raw['paths'])) {
if (!isRecord(entry)) {
continue;
}
paths.push({
requestedPath: coverageString(entry['requested_path']),
path: normalizeCoveragePath(coverageString(entry['path'])),
status: coverageString(entry['status']),
freshness: coverageString(entry['freshness']),
recommendedAction: coverageString(entry['recommended_action']),
coverage: readCoverageRows(entry['coverage']),
});
}
const scopes: CoverageScope[] = [];
const rawScopes = coverageArray(raw['scopes']);
for (const entry of rawScopes) {
if (!isRecord(entry)) {
continue;
}
const scope: CoverageScope = {
requestedScope: coverageString(entry['requested_scope']),
scope: coverageString(entry['scope']),
status: coverageString(entry['status']),
total: asNumber(entry['total']),
// Production reports continuation on the response envelope. A
// scope's `truncated` also remains true on its final partial page,
// so that flag cannot determine whether another page is needed.
hasMore: typeof entry['has_more'] === 'boolean' ? entry['has_more']
: rawScopes.length === 1 && raw['has_more'] === true,
entries: readCoverageRows(entry['entries']),
};
if (entry['next_offset'] !== undefined) {
scope.nextOffset = asNumber(entry['next_offset']);
} else if (rawScopes.length === 1 && raw['next_offset'] !== undefined) {
scope.nextOffset = asNumber(raw['next_offset']);
}
scopes.push(scope);
}
return {
project: coverageString(raw['project']),
metadata: {
generation: coverageString(meta['generation']),
indexMode: coverageString(meta['index_mode']),
recordedAt: coverageString(meta['recorded_at']),
recordingStatus: coverageString(meta['recording_status']),
ignoredFilesStored: asNumber(meta['ignored_files_stored']),
ignoredFilesTotal: asNumber(meta['ignored_files_total']),
hashRecordsComplete: meta['hash_records_complete'] === true,
coverageVersion: asNumber(meta['coverage_version']),
generationMatches: meta['generation_matches'] === true,
},
paths,
scopes,
caveat: coverageString(raw['caveat']),
};
}
// --------------------------------------------------------- Der Join ---------
/** Ein Befund ueber genau einen Pfad, aus allen Quellen zusammengelegt. */
export interface CoverageRecord {
path: string;
kind: 'file' | 'dir';
state: CoverageState;
/** Der Grund des Servers. Leer heisst: er hat keinen genannt. */
reason: string;
/** Welche Quellen diesen Pfad genannt haben, in der Reihenfolge des Eintreffens. */
sources: string[];
}
/** Was der Join ueber ein Projekt weiss. */
export interface CoverageIndex {
/** Je Pfad genau ein Befund. Was hier fehlt, hat keine Quelle genannt. */
records: ReadonlyMap<string, CoverageRecord>;
/** Ehrliche Zeilen ueber Listen, die der Server gekappt hat. */
truncations: string[];
/** All recorded root-scope rows were returned, not all repository files indexed. */
listingComplete?: boolean;
counts: {
partial: number;
skipped: number;
notIndexedDirs: number;
notIndexedFiles: number;
scopeEntries: number;
};
}
/** Ein Join ohne jede Quelle. Nicht "alles indiziert", sondern "noch nichts gefragt". */
export const EMPTY_COVERAGE: CoverageIndex = {
records: new Map<string, CoverageRecord>(),
truncations: [],
counts: { partial: 0, skipped: 0, notIndexedDirs: 0, notIndexedFiles: 0, scopeEntries: 0 },
};
function putRecord(
records: Map<string, CoverageRecord>,
entry: { path: string; kind: 'file' | 'dir'; state: CoverageState; reason: string; source: string },
): void {
const path = normalizeCoveragePath(entry.path);
if (path.length === 0) {
return;
}
const existing = records.get(path);
if (existing === undefined) {
records.set(path, {
path,
kind: entry.kind,
state: entry.state,
reason: entry.reason,
sources: [entry.source],
});
return;
}
if (!existing.sources.includes(entry.source)) {
existing.sources.push(entry.source);
}
// Ein Ordner bleibt ein Ordner: die Scope-Liste nennt Pfade ohne Art, und
// eine Datei daraus duerfte einen bekannten Ordner nicht ueberschreiben.
if (entry.kind === 'dir') {
existing.kind = 'dir';
}
const worst = worstCoverage(existing.state, entry.state);
if (worst !== existing.state) {
existing.state = worst;
existing.reason = entry.reason;
} else if (existing.reason.length === 0) {
existing.reason = entry.reason;
}
}
/**
* Die Quellen zu einem Befund je Pfad zusammenlegen.
*
* Der Graph steht hier nicht: er sagt ueber eine Datei nur, dass sie da ist,
* und "da" ist die Abwesenheit eines Befundes. Wer in keiner Liste steht, gilt
* als `indexed`, und genau das ist die Konfliktregel: eine Datei, die im
* Graphen UND in `parse_partial` steht, ist partiell, nicht vollstaendig.
*/
export function buildCoverageIndex(input: {
status?: IndexStatusCoverage | undefined;
scopes?: readonly CoverageScope[] | undefined;
}): CoverageIndex {
const records = new Map<string, CoverageRecord>();
const truncations: string[] = [];
const counts = { partial: 0, skipped: 0, notIndexedDirs: 0, notIndexedFiles: 0, scopeEntries: 0 };
const scopeReadings = new Map<string, { last: CoverageScope; total: number; consistent: boolean; rows: Map<string, CoverageRow> }>();
for (const scope of input.scopes ?? []) {
const key = scope.scope || '.';
const reading = scopeReadings.get(key) ?? { last: scope, total: scope.total, consistent: true, rows: new Map<string, CoverageRow>() };
reading.consistent &&= scope.total === reading.total
&& ['known_gaps', 'no_recorded_issue', 'complete'].includes(scope.status);
reading.last = scope;
for (const row of scope.entries) reading.rows.set(`${row.path}\0${row.kind}`, row);
scopeReadings.set(key, reading);
}
const complete = (reading: NonNullable<ReturnType<typeof scopeReadings.get>>) =>
reading.consistent && !reading.last.hasMore && reading.rows.size === reading.total;
const rootReading = scopeReadings.get('.');
const listingComplete = rootReading !== undefined && complete(rootReading);
const rootRows = listingComplete ? [...rootReading!.rows.values()] : [];
const listedKind = (kind: string) => rootRows.filter((row) => row.kind === kind).length;
const status = input.status;
if (status !== undefined) {
for (const entry of status.parsePartial) {
putRecord(records, {
path: entry.path,
kind: 'file',
state: 'partial',
reason: entry.errorRanges,
source: 'index_status.parse_partial',
});
}
for (const entry of status.skipped) {
putRecord(records, {
path: entry.path,
kind: 'file',
state: 'skipped',
reason: [entry.reason, entry.phase].filter((part) => part.length > 0).join(' / '),
source: 'index_status.skipped',
});
}
for (const path of status.notIndexedDirs) {
putRecord(records, {
path,
kind: 'dir',
state: 'not-indexed',
reason: '',
source: 'index_status.not_indexed.dirs',
});
}
for (const entry of status.notIndexedFiles) {
putRecord(records, {
path: entry.path,
kind: 'file',
state: 'not-indexed',
reason: entry.reason,
source: 'index_status.not_indexed.files',
});
}
counts.partial = status.parsePartialCount;
counts.skipped = status.skippedCount;
counts.notIndexedDirs = status.notIndexedDirsCount;
counts.notIndexedFiles = status.notIndexedFilesCount;
if (status.parsePartialTruncated && (!listingComplete || listedKind('parse_partial') < status.parsePartialCount)) {
truncations.push(
`the server cut the parse_partial list: ${status.parsePartialCount} recorded, fewer listed`,
);
}
const listedSkipped = rootRows.filter((row) => coverageStateForKind(row.kind) === 'skipped').length;
if (status.skippedTruncated && (!listingComplete || listedSkipped < status.skippedCount)) {
truncations.push(
`the server cut the skipped list: ${status.skippedCount} recorded, fewer listed`,
);
}
if (status.notIndexedTruncated && (!listingComplete || listedKind('not_indexed_dir') < status.notIndexedDirsCount || listedKind('not_indexed_file') < status.notIndexedFilesCount)) {
truncations.push(
'the server cut the not_indexed list: '
+ `${status.notIndexedDirsCount} folders and ${status.notIndexedFilesCount} files recorded, fewer listed`,
);
}
}
for (const scope of input.scopes ?? []) {
for (const row of scope.entries) {
const state = coverageStateForKind(row.kind);
putRecord(records, {
path: row.path,
kind: row.kind === 'not_indexed_dir' ? 'dir' : 'file',
state,
reason: row.detail,
source: `check_index_coverage.scope:${scope.scope.length > 0 ? scope.scope : '.'}`,
});
counts.scopeEntries += 1;
}
}
for (const [scope, reading] of scopeReadings) {
if (!complete(reading)) {
truncations.push(
`the coverage reading under "${scope}" is incomplete or inconsistent: `
+ `${reading.total} recorded, ${reading.rows.size} distinct rows loaded`,
);
}
}
return { records, truncations, counts, listingComplete };
}
/**
* Die schlechteste Stufe unter einem Ordner, seine eigene eingeschlossen.
*
* Ueber den Coverage-Index und nicht ueber die geladenen Ebenen, und das ist
* der Grund, warum der Punkt-Marker eines zugeklappten Ordners stimmt: die
* Ebenen kommen einzeln und spaet, die Befunde kommen vollstaendig und frueh.
*/
export function aggregateCoverage(index: CoverageIndex, dirPath: string): CoverageState {
const prefix = `${dirPath}/`;
let worst: CoverageState = 'indexed';
for (const record of index.records.values()) {
if (record.path === dirPath || record.path.startsWith(prefix)) {
worst = worstCoverage(worst, record.state);
}
}
return worst;
}
function ensureLevel(levels: Map<string, TreeLevel>, path: string): TreeLevel {
const existing = levels.get(path);
if (existing !== undefined) {
return existing;
}
const created: TreeLevel = {
path,
files: 0,
symbols: 0,
children: [],
foldedDuplicates: 0,
droppedNonPaths: 0,
synthetic: true,
};
levels.set(path, created);
return created;
}
function graftPath(levels: Map<string, TreeLevel>, path: string, kind: 'file' | 'dir'): void {
const parent = parentPath(path);
if (parent.length > 0) {
graftPath(levels, parent, 'dir');
}
const level = ensureLevel(levels, parent);
if (level.children.some((child) => child.path === path)) {
return;
}
level.children.push({
name: path.slice(path.lastIndexOf('/') + 1),
path,
kind,
symbols: 0,
files: 0,
});
}
/**
* Die Vereinigung: die Ebenen aus dem Graphen, ergaenzt um jeden Pfad, den nur
* die Coverage-Listen kennen, und jede Zeile mit ihrer Stufe versehen.
*
* Die Ebenen werden kopiert und nicht veraendert. Ein Join, der die Antworten
* des Servers an Ort und Stelle beschriftet, macht aus zweimal Lesen zweimal
* etwas anderes, und der Explorer zeichnet oefter, als der Server antwortet.
*/
export function mergeCoverageIntoLevels(
levels: ReadonlyMap<string, TreeLevel>,
index: CoverageIndex,
): Map<string, TreeLevel> {
const merged = new Map<string, TreeLevel>();
for (const [path, level] of levels) {
merged.set(path, { ...level, children: level.children.map((child) => ({ ...child })) });
}
for (const record of index.records.values()) {
graftPath(merged, record.path, record.kind);
}
for (const level of merged.values()) {
for (const child of level.children) {
const record = index.records.get(child.path);
child.coverage = child.kind === 'dir'
? aggregateCoverage(index, child.path)
: record?.state ?? 'indexed';
if (record !== undefined && record.reason.length > 0) {
child.coverageReason = record.reason;
}
if (record !== undefined) {
child.coverageSources = [...record.sources];
}
}
level.children.sort(compareChildren);
}
return merged;
}