Skip to content

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.

18.2 KB
Raw Blame
/**
 * Parser fuer das kompakte Zeilenformat, das der C-Server im MCP-Text liefert.
 *
 * Der Server antwortet auf query_graph und Verwandte nicht mit JSON, sondern
 * mit einem Kopf, eingerueckten Datenzeilen und einem Fuss:
 *
 *     rows: 5  (cols: b.name r.line)
 *       validateUser "24"
 *     total: 5
 *
 * search_graph benutzt eine zweite, aehnliche Form mit `results:` statt
 * `rows:`. Beide werden getrennt geparst statt in einem Format vereinheitlicht,
 * weil sie verschiedene Dinge sagen: `total` in der Zeilenform ist die Zahl
 * der Treffer, `has_more` in der Suchform sagt zusaetzlich, ob der Server
 * abgeschnitten hat. Ein gemeinsamer Rueckgabetyp muesste eines der beiden
 * erfinden oder verschweigen.
 *
 * Der Parser rundet nichts ab: eine Zeile mit einer anderen Zellenzahl als der
 * Kopf ankuendigt ist ein Fehler und wird nicht mit Leerwerten aufgefuellt.
 */

/** Eine geparste Zeilenantwort. */
export interface CompactRows {
    /** Spaltennamen aus dem Kopf, zum Beispiel `b.name` und `r.line`. */
    columns: string[];
    /** Datenzeilen, Zellen in Spaltenreihenfolge und bereits entquotet. */
    rows: string[][];
    /** Der `total:`-Wert des Servers. Kann groesser sein als `rows.length`. */
    total: number;
    /** Der `hint:`-Text, den der Server bei leeren Ergebnissen mitschickt. */
    hint?: string;
    /**
     * Die Fusszeilen, die der Server seit dem schlanken Ausgabevertrag
     * (#1597) mitschickt: wie viele Zeilen geliefert wurden, ob `total` exakt
     * oder eine Untergrenze ist (`eq` / `gte`), ob mehr da waere und ob
     * gekappt wurde. Optional, weil die Aufzeichnungen von vor dem Vertrag
     * sie nicht tragen; wo sie da sind, sind sie die ehrlichere Auskunft.
     */
    returned?: number;
    totalRelation?: string;
    hasMore?: boolean;
    truncated?: boolean;
    offset?: number;
    nextOffset?: number;
    nextCursor?: string;
    truncationReason?: string;
    warning?: string;
}

/** Eine geparste search_graph-Antwort. */
export interface SearchResults {
    /** Der `total:`-Wert des Servers. */
    total: number;
    /** Der `search_mode:`-Wert, zum Beispiel `bm25`. */
    mode: string;
    /** Spaltennamen aus dem `results:`-Kopf. */
    columns: string[];
    /** Trefferzeilen, Zellen in Spaltenreihenfolge. */
    rows: string[][];
    /** True, wenn der Server abgeschnitten hat und mehr da waere. */
    hasMore: boolean;
    /** Die weiteren Fusszeilen des schlanken Vertrags (#1597), siehe CompactRows. */
    returned?: number;
    totalRelation?: string;
    truncated?: boolean;
    /** Was bm25_emit_metadata_tree (src/mcp/mcp.c) ausserdem schreibt: die naechste Seite,
     * warum gekappt wurde, ein gesaettigtes Kandidatenfenster und ein zu kleines Budget. */
    nextOffset?: number;
    truncationReason?: string;
    candidateWindowSaturated?: boolean;
    continuationRequiresHigherBudget?: boolean;
    maxOutputBytes?: number;
    outputBudgetFloorExceeded?: boolean;
    hint?: string;
}

/** Fusszeilen der Suchantwort mit Zahl, Wahrheitswert oder Text (Handtest 04.10.: jede
 * unbekannte liess die Suche mit "Index search unavailable" scheitern). */
const SEARCH_NUMBER_LINE = /^(next_offset|max_output_bytes):\s*(\d+)\s*$/;
const SEARCH_FLAG_LINE = /^(candidate_window_saturated|continuation_requires_higher_budget|output_budget_floor_exceeded):\s*(true|false)\s*$/;
const SEARCH_TEXT_LINE = /^(truncation_reason|hint):\s*(.*)$/;

const ROWS_HEAD = /^rows:\s*(\d+)\s*\(cols:\s*([^)]*)\)\s*$/;
const RESULTS_HEAD = /^results:\s*(\d+)\s*\(cols:\s*([^)]*)\)\s*$/;
const TOTAL_LINE = /^total:\s*(\d+)\s*$/;
const HINT_LINE = /^hint:\s*(.*)$/;
const MODE_LINE = /^search_mode:\s*(\S+)\s*$/;
const HAS_MORE_LINE = /^has_more:\s*(true|false)\s*$/;
const RETURNED_LINE = /^returned:\s*(\d+)\s*$/;
const TOTAL_RELATION_LINE = /^total_relation:\s*(\S+)\s*$/;
const TRUNCATED_LINE = /^truncated:\s*(true|false)\s*$/;
const DATA_LINE = /^ {2}\S/;

/** Zerlegt eine Datenzeile in Zellen und nimmt Anfuehrungszeichen weg. */
export function splitCells(line: string): string[] {
    return cellTokens(line).map(cell => cell.value);
}

/** Quoted @N+ values are literals; retain that distinction until expansion. */
function cellTokens(line: string): { value: string; quoted: boolean }[] {
    const cells: { value: string; quoted: boolean }[] = [];
    let i = 0;
    while (i < line.length) {
        while (i < line.length && (line[i] === ' ' || line[i] === '\t')) {
            i += 1;
        }
        if (i >= line.length) {
            break;
        }
        if (line[i] === '"') {
            i += 1;
            let buf = '';
            let closed = false;
            while (i < line.length) {
                const ch = line[i];
                if (ch === '\\' && i + 1 < line.length) {
                    buf += line[i + 1];
                    i += 2;
                    continue;
                }
                if (ch === '"') {
                    i += 1;
                    closed = true;
                    break;
                }
                buf += ch;
                i += 1;
            }
            if (!closed) {
                throw new Error(
                    `kompakte Zeile hat ein nicht geschlossenes Anfuehrungszeichen: ${line.trim()}`,
                );
            }
            cells.push({ value: buf, quoted: true });
            continue;
        }
        const start = i;
        while (i < line.length && line[i] !== ' ' && line[i] !== '\t') {
            i += 1;
        }
        cells.push({ value: line.slice(start, i), quoted: false });
    }
    return cells;
}

function unquote(value: string): string {
    const trimmed = value.trim();
    if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
        return splitCells(trimmed)[0] ?? '';
    }
    return trimmed;
}

function readColumns(raw: string): string[] {
    const columns = raw.trim().split(/\s+/).filter((c) => c.length > 0);
    if (columns.length === 0) {
        throw new Error('kompakter Kopf nennt keine Spalten');
    }
    return columns;
}

function collectRows(
    lines: string[],
    from: number,
    columns: string[],
    label: string,
    refs?: ReadonlyMap<number, string>,
): { rows: string[][]; next: number } {
    const rows: string[][] = [];
    let i = from;
    while (i < lines.length && DATA_LINE.test(lines[i])) {
        const cells = cellTokens(lines[i].slice(2)).map(cell => {
            const ref = !cell.quoted && refs ? /^@(\d+)\+(.*)$/.exec(cell.value) : null;
            if (!ref) return cell.value;
            const prefix = refs!.get(Number(ref[1]));
            if (prefix === undefined) throw new Error(`${label}: unknown reference @${ref[1]}`);
            // Prefix entries are declarations, never recursively expanded.
            return prefix + ref[2];
        });
        if (cells.length !== columns.length) {
            throw new Error(
                `${label}: Zeile ${i + 1} hat ${cells.length} Zellen, der Kopf nennt ` +
                    `${columns.length} Spalten (${columns.join(' ')}): ${lines[i].trim()}`,
            );
        }
        rows.push(cells);
        i += 1;
    }
    return { rows, next: i };
}

function readReferences(lines: string[], from: number, key: 'rows' | 'results'):
    { refs?: ReadonlyMap<number, string>; next: number } {
    const head = new RegExp(`^${key}_refs:\\s*(\\d+)\\s*\\(cols:\\s*id\\s+prefix\\)\\s*$`).exec(lines[from]);
    if (!head) return { next: from };
    const count = Number(head[1]);
    const collected = collectRows(lines, from + 1, ['id', 'prefix'], `${key}_refs`);
    if (!Number.isSafeInteger(count) || collected.rows.length !== count)
        throw new Error(`${key}_refs: declared count does not match reference rows`);
    const refs = new Map<number, string>();
    for (const [id, prefix] of collected.rows) {
        const number = Number(id);
        if (!/^\d+$/.test(id) || !Number.isSafeInteger(number) || refs.has(number))
            throw new Error(`${key}_refs: invalid or duplicate reference id ${id}`);
        refs.set(number, prefix);
    }
    if (lines[collected.next]?.trim() !== `${key}_ref_rule: @N+suffix=prefix+suffix`)
        throw new Error(`${key}_refs: missing or unsupported reference rule`);
    return { refs, next: collected.next + 1 };
}

function validateCounts(parsed: CompactRows | SearchResults): void {
    for (const value of [parsed.total, parsed.returned, 'offset' in parsed ? parsed.offset : undefined,
        'nextOffset' in parsed ? parsed.nextOffset : undefined]) {
        if (value !== undefined && (!Number.isSafeInteger(value) || value < 0))
            throw new Error('Invalid compact response count');
    }
    if (parsed.total < parsed.rows.length || (parsed.returned !== undefined && parsed.returned !== parsed.rows.length))
        throw new Error('Compact response counts contradict returned rows');
    if (parsed.totalRelation !== undefined && parsed.totalRelation !== 'eq' && parsed.totalRelation !== 'gte')
        throw new Error('Unknown total_relation');
}

/**
 * Parst die Zeilenform (`rows:` / Datenzeilen / `total:` / optional `hint:`).
 *
 * Wirft, wenn der Kopf fehlt, eine Zeile nicht zur Spaltenzahl passt oder der
 * Kopf mehr oder weniger Zeilen ankuendigt, als dann kommen.
 */
export function parseCompactRows(text: string): CompactRows {
    const lines = text.split('\n');
    let i = 0;
    while (i < lines.length && lines[i].trim().length === 0) {
        i += 1;
    }
    if (i >= lines.length) {
        throw new Error('kompakte Antwort war leer');
    }

    const directory = readReferences(lines, i, 'rows');
    i = directory.next;
    const head = ROWS_HEAD.exec(lines[i] ?? '');
    if (head === null) {
        throw new Error(
            `unbekannter Kopf einer kompakten Antwort, erwartet "rows: N  (cols: ...)": ` +
                `${lines[i].trim()}`,
        );
    }
    const declared = Number.parseInt(head[1], 10);
    const columns = readColumns(head[2]);
    i += 1;

    const collected = collectRows(lines, i, columns, 'kompakte Antwort', directory.refs);
    const rows = collected.rows;
    i = collected.next;

    if (rows.length !== declared) {
        throw new Error(
            `kompakte Antwort kuendigt rows: ${declared} an, geliefert wurden ${rows.length}`,
        );
    }

    let total: number | undefined;
    let hint: string | undefined;
    let returned: number | undefined;
    let totalRelation: string | undefined;
    let hasMore: boolean | undefined;
    let truncated: boolean | undefined;
    const metadata: Pick<CompactRows, 'offset' | 'nextOffset' | 'nextCursor' | 'truncationReason' | 'warning'> = {};
    for (; i < lines.length; i += 1) {
        const line = lines[i];
        if (line.trim().length === 0) {
            continue;
        }
        const totalMatch = TOTAL_LINE.exec(line);
        if (totalMatch !== null) {
            total = Number.parseInt(totalMatch[1], 10);
            continue;
        }
        const hintMatch = HINT_LINE.exec(line);
        if (hintMatch !== null) {
            hint = unquote(hintMatch[1]);
            continue;
        }
        const returnedMatch = RETURNED_LINE.exec(line);
        if (returnedMatch !== null) {
            returned = Number.parseInt(returnedMatch[1], 10);
            continue;
        }
        const relationMatch = TOTAL_RELATION_LINE.exec(line);
        if (relationMatch !== null) {
            totalRelation = relationMatch[1];
            continue;
        }
        const hasMoreMatch = HAS_MORE_LINE.exec(line);
        if (hasMoreMatch !== null) {
            hasMore = hasMoreMatch[1] === 'true';
            continue;
        }
        const truncatedMatch = TRUNCATED_LINE.exec(line);
        if (truncatedMatch !== null) {
            truncated = truncatedMatch[1] === 'true';
            continue;
        }
        const extra = /^(offset|next_offset|next_cursor|truncation_reason|warning):\s*(.*)$/.exec(line);
        if (extra) {
            const value = unquote(extra[2]);
            if (extra[1] === 'offset' || extra[1] === 'next_offset') {
                if (!/^\d+$/.test(value)) throw new Error(`Invalid ${extra[1]}`);
                metadata[extra[1] === 'offset' ? 'offset' : 'nextOffset'] = Number(value);
            } else if (extra[1] === 'next_cursor') metadata.nextCursor = value;
            else if (extra[1] === 'truncation_reason') metadata.truncationReason = value;
            else metadata.warning = value;
            continue;
        }
        throw new Error(`unbekannte Fusszeile einer kompakten Antwort: ${line.trim()}`);
    }

    if (total === undefined) {
        throw new Error('kompakte Antwort ohne total-Zeile');
    }

    const out: CompactRows = { columns, rows, total, ...metadata };
    if (hint !== undefined) {
        out.hint = hint;
    }
    if (returned !== undefined) {
        out.returned = returned;
    }
    if (totalRelation !== undefined) {
        out.totalRelation = totalRelation;
    }
    if (hasMore !== undefined) {
        out.hasMore = hasMore;
    }
    if (truncated !== undefined) {
        out.truncated = truncated;
    }
    validateCounts(out);
    return out;
}

/**
 * Parst die search_graph-Form (`total:` / `search_mode:` / `results:` /
 * Trefferzeilen / `has_more:`).
 */
export function parseSearchResults(text: string): SearchResults {
    const lines = text.split('\n');
    let total: number | undefined;
    let mode: string | undefined;
    let columns: string[] | undefined;
    let declared: number | undefined;
    let rows: string[][] | undefined;
    let hasMore: boolean | undefined;
    let returned: number | undefined;
    let totalRelation: string | undefined;
    let truncated: boolean | undefined;
    let refs: ReadonlyMap<number, string> | undefined;
    const footers: Pick<SearchResults, 'nextOffset' | 'truncationReason' | 'candidateWindowSaturated' | 'continuationRequiresHigherBudget' | 'maxOutputBytes' | 'outputBudgetFloorExceeded' | 'hint'> = {};

    let i = 0;
    while (i < lines.length) {
        const line = lines[i];
        if (line.trim().length === 0) {
            i += 1;
            continue;
        }
        if (line.startsWith('results_refs:')) {
            if (refs || rows) throw new Error('Duplicate or misplaced results_refs');
            const directory = readReferences(lines, i, 'results');
            if (!directory.refs) throw new Error('Malformed results_refs');
            refs = directory.refs;
            i = directory.next;
            continue;
        }

        const totalMatch = TOTAL_LINE.exec(line);
        if (totalMatch !== null) {
            total = Number.parseInt(totalMatch[1], 10);
            i += 1;
            continue;
        }
        const modeMatch = MODE_LINE.exec(line);
        if (modeMatch !== null) {
            mode = modeMatch[1];
            i += 1;
            continue;
        }
        const hasMoreMatch = HAS_MORE_LINE.exec(line);
        if (hasMoreMatch !== null) {
            hasMore = hasMoreMatch[1] === 'true';
            i += 1;
            continue;
        }
        const returnedMatch = RETURNED_LINE.exec(line);
        if (returnedMatch !== null) {
            returned = Number.parseInt(returnedMatch[1], 10);
            i += 1;
            continue;
        }
        const relationMatch = TOTAL_RELATION_LINE.exec(line);
        if (relationMatch !== null) {
            totalRelation = relationMatch[1];
            i += 1;
            continue;
        }
        const truncatedMatch = TRUNCATED_LINE.exec(line);
        if (truncatedMatch !== null) {
            truncated = truncatedMatch[1] === 'true';
            i += 1;
            continue;
        }
        const numberMatch = SEARCH_NUMBER_LINE.exec(line);
        if (numberMatch !== null) {
            footers[numberMatch[1] === 'next_offset' ? 'nextOffset' : 'maxOutputBytes'] = Number.parseInt(numberMatch[2], 10);
            i += 1;
            continue;
        }
        const flagMatch = SEARCH_FLAG_LINE.exec(line);
        if (flagMatch !== null) {
            const key = flagMatch[1] === 'candidate_window_saturated' ? 'candidateWindowSaturated'
                : flagMatch[1] === 'continuation_requires_higher_budget' ? 'continuationRequiresHigherBudget' : 'outputBudgetFloorExceeded';
            footers[key] = flagMatch[2] === 'true';
            i += 1;
            continue;
        }
        const textMatch = SEARCH_TEXT_LINE.exec(line);
        if (textMatch !== null) {
            footers[textMatch[1] === 'truncation_reason' ? 'truncationReason' : 'hint'] = unquote(textMatch[2].trim());
            i += 1;
            continue;
        }
        const head = RESULTS_HEAD.exec(line);
        if (head !== null) {
            declared = Number.parseInt(head[1], 10);
            columns = readColumns(head[2]);
            const collected = collectRows(lines, i + 1, columns, 'Suchantwort', refs);
            rows = collected.rows;
            i = collected.next;
            continue;
        }
        throw new Error(`unbekannte Zeile in der Suchantwort: ${line.trim()}`);
    }

    if (columns === undefined || rows === undefined || declared === undefined) {
        throw new Error(
            'unbekannter Kopf einer Suchantwort, erwartet "results: N  (cols: ...)"',
        );
    }
    if (rows.length !== declared) {
        throw new Error(
            `Suchantwort kuendigt results: ${declared} an, geliefert wurden ${rows.length}`,
        );
    }
    if (total === undefined) {
        throw new Error('Suchantwort ohne total-Zeile');
    }
    if (mode === undefined) {
        throw new Error('Suchantwort ohne search_mode-Zeile');
    }
    if (hasMore === undefined) {
        throw new Error('Suchantwort ohne has_more-Zeile');
    }

    const out: SearchResults = { total, mode, columns, rows, hasMore, ...footers };
    if (returned !== undefined) {
        out.returned = returned;
    }
    if (totalRelation !== undefined) {
        out.totalRelation = totalRelation;
    }
    if (truncated !== undefined) {
        out.truncated = truncated;
    }
    validateCounts(out);
    return out;
}

/** Verbindet Spaltennamen und Zellen zu einem Objekt je Zeile. */
export function rowsAsObjects(parsed: CompactRows | SearchResults): Record<string, string>[] {
    return parsed.rows.map((cells) => {
        const record: Record<string, string> = {};
        parsed.columns.forEach((column, index) => {
            record[column] = cells[index];
        });
        return record;
    });
}