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.

20.1 KB
Raw Blame
/**
 * Eine getypte Methode je Engine-Werkzeug, gesprochen ueber POST /rpc.
 *
 * Diese Schicht hat drei Aufgaben und keine vierte: das Werkzeug benennen, die
 * Antwort auspacken und ihre Form pruefen. Sie kennt kein Produktvokabular und
 * faellt kein Urteil darueber, was ein Ergebnis bedeutet; das ist Sache des
 * Providers. Vorbild ist IntelligenceClient aus CodeAtlasIDE
 * (theia-extensions/codeatlas-intelligence/src/node/client/intelligence-client.ts),
 * die Methodenliste ist dieselbe. Der Transport ist ein anderer, und die
 * Unterschiede sind der Inhalt dieser Datei.
 *
 * **Kein Kindprozess.** Das Original startete je Aufruf die CLI. Hier laeuft
 * alles im Browser gegen den Server aus PR 1860, also ueber fetch. Nichts
 * unter src/** darf einen Prozess starten, und nichts hier tut es.
 *
 * **Zwei Drahtformen statt einer.** Die 0.9.0-CLI antwortete auf alles mit
 * JSON. Der Server antwortet je Werkzeug verschieden, und das ist gegen den
 * gebauten Server geprueft, nicht angenommen:
 *
 * - `query_graph` liefert die kompakte Zeilenform. Sie geht durch
 *   parseCompactRows und wird zu `{columns, rows}`, also genau die Form, die
 *   der portierte Provider vorher von der CLI bekam.
 * - `search_graph` liefert bei einer BM25-Anfrage die flache Suchform, die
 *   parseSearchResults liest.
 * - `list_projects`, `index_status` und `get_code_snippet` liefern JSON von
 *   sich aus.
 * - `detect_changes`, `get_architecture` und `trace_path` liefern eine
 *   Textform fuer Menschen, es sei denn, man bittet mit `format: "json"` um
 *   Daten. Genau das tun die Methoden unten. Ein Parser fuer die Textform
 *   waere ein zweiter, stiller Vertrag ueber eine Anzeige gewesen.
 *
 * **Drei Werkzeuge gibt es hier nicht.** `index_repository`, `delete_project`
 * und `ingest_traces` beantwortet die Read-only-Allowlist des Servers mit 403
 * und -32601. Die Methoden sind trotzdem da und werfen sofort, statt zu
 * fehlen: eine fehlende Methode waere ein Uebersetzungsfehler beim Aufrufer,
 * ein klarer Fehler ist eine Aussage ueber diese Oberflaeche. Indiziert wird
 * ueber die CLI, nicht von hier.
 */

import { parseCompactRows, parseSearchResults, rowsAsObjects } from './compact-rows';
import type { CompactRows, SearchResults } from './compact-rows';
import { callToolJson, callToolText, RpcError } from './rpc-transport';
import type { CallToolOptions } from './rpc-transport';
import { EngineError, EngineUnavailableError } from './engine-errors';
import {
    normalizeCell,
    readArchitecture,
    readCodeSnippet,
    readDetectChanges,
    readIndexStatus,
    readListProjects,
    readPathResult,
    readSearchRows,
} from './rpc-schemas';
import type {
    ArchitectureResult,
    CodeSnippetResult,
    DetectChangesResult,
    IndexStatusResult,
    ListProjectsResult,
    PathResult,
    QueryGraphResult,
    SearchGraphResult,
} from './rpc-schemas';

/** Werkzeuge, die die Read-only-Allowlist des Servers nicht anbietet. */
export const RPC_BLOCKED_TOOLS = ['index_repository', 'delete_project', 'ingest_traces'] as const;

/** Stellschrauben des Clients. Ohne base ist der Ursprung der ausliefernde Server. */
export interface RpcClientOptions {
    /** Ursprung des Servers, ohne Schraegstrich am Ende. Leer heisst same-origin. */
    base?: string;
    /** Ersetzbares fetch, damit Tests ohne Netz laufen. */
    fetch?: typeof globalThis.fetch;
    /** Abbruchsignal, an jeden Aufruf durchgereicht. */
    signal?: AbortSignal;
}

/**
 * Eine tabellarische Antwort als ein Objekt je Zeile, benannt nach den Spalten,
 * die die Abfrage verlangt hat.
 *
 * Die Spaltennamen behalten ihre Engine-Schreibweise, und zwar mit Absicht: der
 * einzige Code, der sie liest, ist der Abfragebauer, der sie geschrieben hat.
 */
export function rowsToObjects(columns: string[], rows: string[][]): Record<string, string>[] {
    return rows.map((row) => {
        const out: Record<string, string> = {};
        columns.forEach((column, index) => {
            out[column] = row[index] ?? '';
        });
        return out;
    });
}

/**
 * Was ein gescheiterter Aufruf fuer die Produktlogik bedeutet.
 *
 * Der Transport kennt vier Arten des Scheiterns; der Provider unterscheidet
 * zwei Lagen, und nur diese zwei. "Die Engine hat geantwortet und nein gesagt"
 * ist eine Aussage ueber Projekt oder Abfrage und fuehrt zu notIndexed. "Es hat
 * niemand geantwortet" ist keine Aussage ueber den Code des Lesers und fuehrt
 * zu unknown. Die Zuordnung steht hier, damit sie einmal existiert:
 *
 * - fetch selbst hat abgelehnt: kein Server, kein Netz, abgebrochen. Nicht
 *   erreichbar.
 * - der Server bietet das Werkzeug nicht an (403 oder -32601). Nicht
 *   erreichbar fuer diese Faehigkeit, und das ist keine Aussage ueber das
 *   Projekt.
 * - HTTP 5xx: der Server ist da und kaputt. Nicht erreichbar.
 * - alles andere, inklusive einer Antwort in unerwarteter Form: die Engine hat
 *   geantwortet, also ein Engine-Fehler.
 */
function asEngineFailure(tool: string, error: unknown): Error {
    if (error instanceof RpcError) {
        if (error.notAllowed) {
            return new EngineUnavailableError(
                'not-allowed',
                `${tool}: dieser Server bietet das Werkzeug auf /rpc nicht an (${error.message})`,
                tool,
            );
        }
        if (error.kind === 'http' && (error.status ?? 0) >= 500) {
            return new EngineUnavailableError('server-error', error.message, tool);
        }
        return new EngineError(tool, error.message, { status: error.status });
    }
    const message = error instanceof Error ? error.message : String(error);
    return new EngineUnavailableError('unreachable', `${tool}: ${message}`, tool);
}

/** Eine Antwort, die ankam, aber nicht zu lesen war. Die Engine lief, also ein Engine-Fehler. */
function asParseFailure(tool: string, error: unknown): EngineError {
    const message = error instanceof Error ? error.message : String(error);
    return new EngineError(tool, `Antwort war nicht lesbar: ${message}`);
}

export class RpcIntelligenceClient {

    constructor(protected readonly options: RpcClientOptions = {}) { }

    /** Die Transportoptionen dieses Clients, je Aufruf frisch zusammengesetzt. */
    protected callOptions(): CallToolOptions {
        const opts: CallToolOptions = {};
        if (this.options.base !== undefined) {
            opts.base = this.options.base;
        }
        if (this.options.fetch !== undefined) {
            opts.fetch = this.options.fetch;
        }
        if (this.options.signal !== undefined) {
            opts.signal = this.options.signal;
        }
        return opts;
    }

    /**
     * Rohtext eines Werkzeugs, mit der Fehlerzuordnung dieser Schicht.
     *
     * `signal` ist je Aufruf und nicht je Client, und das ist seit W7b der
     * Unterschied, auf den es ankommt: der Client lebt so lange wie die Seite,
     * eine Suchanfrage nur bis zum naechsten Tastendruck. Ein Signal am Client
     * koennte also nur alles abbrechen oder nichts.
     */
    protected async text(
        tool: string,
        args: Record<string, unknown>,
        call: { signal?: AbortSignal } = {},
    ): Promise<string> {
        try {
            return await callToolText(tool, args, {
                ...this.callOptions(),
                ...(call.signal === undefined ? {} : { signal: call.signal }),
            });
        } catch (error) {
            throw asEngineFailure(tool, error);
        }
    }

    /** JSON eines Werkzeugs. `format: "json"` gehoert zur Bitte, nicht zur Antwort. */
    protected async json(tool: string, args: Record<string, unknown>): Promise<unknown> {
        try {
            return await callToolJson(tool, { ...args, format: 'json' }, this.callOptions());
        } catch (error) {
            throw asEngineFailure(tool, error);
        }
    }

    /** Ein Werkzeug, das diese Oberflaeche nicht hat, mit einer Begruendung statt einer Ausrede. */
    protected refuse(tool: string): never {
        throw new EngineUnavailableError(
            'not-allowed',
            `${tool}: die Read-only-Allowlist des Servers bietet dieses Werkzeug auf /rpc nicht an. ` +
                'Schreibende Vorgaenge laufen ueber die CLI, nicht ueber diese Oberflaeche.',
            tool,
        );
    }

    /**
     * Tabellarische Abfrage.
     *
     * Der Weg durch parseCompactRows ist der Kern dieses Zyklus: der Server
     * schickt hier keine Tabelle als JSON, sondern Kopf, eingerueckte Zeilen
     * und Fuss. Was herauskommt, ist die Form `{columns, rows}`, die der
     * portierte Provider von der 0.9.0-CLI kannte, damit die Umstellung des
     * Transports an dieser Stelle endet.
     *
     * Der Leermarker der kompakten Form wird dabei zur leeren Zeichenkette.
     * Siehe EMPTY_CELL in rpc-schemas.ts: die JSON-Form derselben Abfrage
     * schreibt an derselben Stelle `""`, und ohne die Uebersetzung wuerde ein
     * Bindestrich als Dateiname durch das Produkt wandern.
     */
    async queryGraph(project: string, query: string, cursor?: string,
        /* Groessere Seiten fuer Lader, die alles brauchen (Galaxy-Scope, Handtest K8). */
        budget?: { maxRows?: number; maxOutputTokens?: number }): Promise<QueryGraphResult> {
        const text = await this.text('query_graph', { project, query, ...(cursor ? { cursor } : {}),
            ...(budget?.maxRows ? { max_rows: budget.maxRows } : {}),
            ...(budget?.maxOutputTokens ? { max_output_tokens: budget.maxOutputTokens } : {}) });
        let parsed: CompactRows;
        try {
            parsed = parseCompactRows(text);
        } catch (error) {
            throw asParseFailure('query_graph', error);
        }
        return {
            ...parsed,
            rows: parsed.rows.map((cells) => cells.map(normalizeCell)),
        };
    }

    /** Tabellarische Abfrage, schon als ein Objekt je Zeile. */
    async queryRows(project: string, query: string): Promise<Record<string, string>[]> {
        const result = await this.queryGraph(project, query);
        const rows = [...result.rows];
        let page = result;
        const cursors = new Set<string>();
        while (page.hasMore || page.truncated || page.nextCursor) {
            if (!page.nextCursor || cursors.has(page.nextCursor) || cursors.size >= 20 || rows.length >= 10000) {
                throw new EngineError('query_graph', `Incomplete query results: ${page.truncationReason ?? 'retrieval bound reached'} (${rows.length} rows read).`);
            }
            if (page.nextOffset !== undefined && page.nextOffset !== rows.length)
                throw new EngineError('query_graph', 'Query continuation does not follow the returned rows.');
            cursors.add(page.nextCursor);
            page = await this.queryGraph(project, query, page.nextCursor);
            if (page.offset !== rows.length || page.total !== result.total
                || JSON.stringify(page.columns) !== JSON.stringify(result.columns) || page.rows.length === 0)
                throw new EngineError('query_graph', 'Query pages disagree about their result snapshot.');
            rows.push(...page.rows);
        }
        if (page.totalRelation === 'gte' || (result.total !== undefined && result.total > rows.length))
            throw new EngineError('query_graph', `Incomplete query results (${rows.length} rows read).`);
        return rowsToObjects(result.columns, rows);
    }

    async listProjects(): Promise<ListProjectsResult> {
        const projects: ListProjectsResult['projects'] = [];
        const names = new Set<string>();
        let offset = 0;
        let total: number | undefined;
        for (let pageNumber = 0; pageNumber < 100; pageNumber++) {
            const raw = await this.json('list_projects', { limit: 500, offset });
            let page: ListProjectsResult;
            try { page = readListProjects(raw); }
            catch (error) { throw asParseFailure('list_projects', error); }
            if ((page.offset !== undefined && page.offset !== offset) || (page.returned !== undefined && page.returned !== page.projects.length))
                throw new EngineError('list_projects', 'Project pagination did not match the requested page.');
            if (total !== undefined && page.total !== undefined && total !== page.total)
                throw new EngineError('list_projects', 'Project inventory changed during pagination. Refresh to read it again.');
            total ??= page.total;
            for (const project of page.projects) {
                if (names.has(project.name)) throw new EngineError('list_projects', 'Project pagination repeated a project.');
                names.add(project.name); projects.push(project);
            }
            const next = offset + page.projects.length;
            if (page.hasMore !== true) {
                if (page.nextOffset !== undefined || (total !== undefined && total !== projects.length))
                    throw new EngineError('list_projects', 'Incomplete project inventory.');
                return { projects };
            }
            if (!page.projects.length || page.nextOffset !== next || next <= offset || (total !== undefined && next >= total))
                throw new EngineError('list_projects', 'Project pagination did not advance.');
            offset = next;
        }
        throw new EngineError('list_projects', 'Project inventory exceeded the 100-page retrieval limit.');
    }

    async indexStatus(project: string): Promise<IndexStatusResult> {
        return readIndexStatus(await this.json('index_status', { project }));
    }

    /**
     * Dieselbe Antwort, ungedeutet.
     *
     * `index_status` traegt neben den Kennzahlen eine Coverage-Beilage
     * (`parse_partial`, `skipped`, `not_indexed`). Sie wird hier absichtlich
     * nicht gelesen: gedeutet wird sie im Join des Explorers
     * (src/app/tree-model.ts), weil erst dort entschieden wird, was eine dieser
     * Listen ueber eine Zeile im Baum aussagt. Zwei Leser fuer dieselben Felder
     * waeren zwei Vertraege ueber dieselbe Antwort.
     */
    async indexStatusPayload(project: string): Promise<unknown> {
        return this.json('index_status', { project });
    }

    /**
     * Der Coverage-Store, gefragt nach Pfaden oder nach Scopes.
     *
     * Zwei Fragen in einem Werkzeug, und sie sind nicht dieselbe: `paths`
     * beantwortet "was weiss der Store ueber genau diese Datei" samt Frische
     * (`freshness`, `recommended_action`), `scopes` listet die Eintraege unter
     * einem Pfad-Praefix, seitenweise ueber `scope_offset`. Die Wurzel heisst
     * `"."`.
     *
     * Die Antwort bleibt roh, aus demselben Grund wie bei `indexStatusPayload`.
     */
    async checkIndexCoverage(
        project: string,
        args: {
            paths?: readonly string[];
            scopes?: readonly string[];
            scopeLimit?: number;
            scopeOffset?: number;
        },
    ): Promise<unknown> {
        return this.json('check_index_coverage', {
            project,
            ...(args.paths === undefined ? {} : { paths: [...args.paths] }),
            ...(args.scopes === undefined ? {} : { scopes: [...args.scopes] }),
            ...(args.scopeLimit === undefined ? {} : { scope_limit: args.scopeLimit }),
            ...(args.scopeOffset === undefined ? {} : { scope_offset: args.scopeOffset }),
        });
    }

    /**
     * Pfade von einem Symbol aus laufen. Liefert die Vereinigung: eine
     * Ablehnung wegen Mehrdeutigkeit ist hier eine normale Antwort, kein
     * Fehler.
     *
     * Richtung und Tiefe in den Woertern des Servers (src/mcp/mcp.c,
     * `trace_path`): `inbound`/`outbound`/`both` und `depth`. Bis zum Review
     * vom 2026-10-02 gingen hier `callers`/`callees` und `max_depth` hinaus,
     * und beides kennt das Schema nicht.
     */
    async tracePath(
        project: string,
        functionName: string,
        args: { direction?: 'inbound' | 'outbound' | 'both'; depth?: number } = {},
    ): Promise<PathResult> {
        return readPathResult(await this.json('trace_path', {
            project,
            function_name: functionName,
            ...(args.direction ? { direction: args.direction } : {}),
            ...(args.depth !== undefined ? { depth: args.depth } : {}),
        }));
    }

    /**
     * Symbole suchen.
     *
     * Gesendet wird `query`, nicht `name_pattern`, und das ist eine bewusste
     * Abweichung vom Original. Der Server beantwortet `name_pattern` in einer
     * nach Modulen gruppierten Anzeigeform und `query` in der flachen Form mit
     * `search_mode` und Rang, die parseSearchResults liest. Was das kostet, ist
     * benannt: die Treffer sind BM25-gerankt statt nach Namensmuster gefiltert,
     * und `is_test` und `is_exported` stehen nicht in der Antwort, bleiben also
     * undefined statt false.
     */
    async searchGraph(
        project: string,
        args: { namePattern?: string; query?: string; limit?: number; signal?: AbortSignal },
    ): Promise<SearchGraphResult> {
        const needle = args.query ?? args.namePattern ?? '';
        const text = await this.text('search_graph', {
            project,
            query: needle,
            ...(args.limit !== undefined ? { limit: args.limit } : {}),
        }, args.signal === undefined ? {} : { signal: args.signal });
        let parsed: SearchResults;
        try {
            parsed = parseSearchResults(text);
        } catch (error) {
            throw asParseFailure('search_graph', error);
        }
        const rows = rowsAsObjects(parsed).map((row) => {
            const out: Record<string, string> = {};
            for (const [key, value] of Object.entries(row)) {
                out[key] = normalizeCell(value);
            }
            return out;
        });
        return readSearchRows(rows, parsed.total);
    }

    /**
     * A symbol's or a module's source.
     *
     * `source_mode: 'full'` is part of the request since the lean output
     * contract (#1597): without it the server outlines every container of
     * 200 lines or more and sends members instead of source. Full source
     * comes in pages of at most 500 lines; `window` names the page, and the
     * answer's `next_start_line` says whether another one follows.
     */
    async getCodeSnippet(
        project: string,
        qualifiedName: string,
        window?: { startLine?: number; maxLines?: number },
    ): Promise<CodeSnippetResult> {
        const args: Record<string, unknown> = {
            project,
            qualified_name: qualifiedName,
            source_mode: 'full',
        };
        if (window?.startLine !== undefined) {
            args['start_line'] = window.startLine;
        }
        if (window?.maxLines !== undefined) {
            args['max_lines'] = window.maxLines;
        }
        return readCodeSnippet(await this.json('get_code_snippet', args));
    }

    async getArchitecture(project: string, aspects: string[] = ['all']): Promise<ArchitectureResult> {
        return readArchitecture(await this.json('get_architecture', { project, aspects }));
    }

    /**
     * Die Aenderungsmenge eines Projekts.
     *
     * Der Vergleichspunkt geht als `since` auf den Draht, so wie das Werkzeug
     * ihn deklariert. Eine fruehere Schreibweise im Referenzprojekt war
     * `since_ref`, und sie sah aus genau dem falschen Grund richtig aus: das
     * Werkzeug nimmt unbekannte Argumente kommentarlos an und antwortet, als
     * waere keines gekommen. Ein Ref unter dem falschen Namen ergibt also eine
     * plausible Antwort ueber den Arbeitsbaum statt einer Ablehnung.
     */
    async detectChanges(
        project: string,
        sinceRef?: string,
        args: { depth?: number } = {},
    ): Promise<DetectChangesResult> {
        return readDetectChanges(await this.json('detect_changes', {
            project,
            // The UI's default is the working tree. Omitting the ref asks the
            // daemon to compare with main, which may not exist in this clone.
            since: sinceRef || 'HEAD',
            ...(args.depth !== undefined ? { depth: args.depth } : {}),
        }));
    }

    async indexRepository(): Promise<never> {
        return this.refuse('index_repository');
    }

    async deleteProject(): Promise<never> {
        return this.refuse('delete_project');
    }

    async ingestTraces(): Promise<never> {
        return this.refuse('ingest_traces');
    }
}