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.

19.9 KB
Raw Blame
import { describe, expect, it } from 'vitest';
import { RpcIntelligenceClient } from './rpc-client';
import { EngineError, EngineUnavailableError } from './engine-errors';
import { isAmbiguousPath } from './rpc-schemas';
import { FakeRpc, RECORDED_PROJECT, listProjectsRoute, rowsText } from '../test-support/rpc-recordings';
import type { Route } from '../test-support/rpc-recordings';

/*
 * Was diese Datei prueft, ist die Uebersetzung zwischen dem, was der Server
 * schickt, und dem, was der portierte Provider erwartet. Die Nutzlasten unten
 * sind Ausschnitte der Antworten, die cbm/build/c/codebase-memory-mcp am
 * 2026-08-28 auf POST /rpc geliefert hat.
 */

function client(routes: Route[]): { client: RpcIntelligenceClient; rpc: FakeRpc } {
    const rpc = new FakeRpc(routes);
    return { client: new RpcIntelligenceClient({ fetch: rpc.fetch }), rpc };
}

describe('tabellarische Abfragen', () => {

    it('liest die kompakte Zeilenform als Spalten und Zeilen', async () => {
        const { client: c } = client([{ tool: 'query_graph', recording: 'calls-out' }]);
        const result = await c.queryGraph(RECORDED_PROJECT, 'MATCH ...');
        expect(result.columns).toEqual([
            'b.name', 'b.qualified_name', 'b.file_path', 'b.start_line', 'r.line',
        ]);
        expect(result.rows).toHaveLength(6);
        expect(result.total).toBe(6);
        expect(result.rows[0][0]).toBe('validateUser');
        // Zahlenspalten kommen gequotet und sollen ohne Anfuehrungszeichen
        // ankommen, damit die Koerzierung des Providers greift.
        expect(result.rows[0][4]).toBe('24');
    });

    it('macht aus dem Leermarker der kompakten Form eine leere Zelle', async () => {
        const { client: c } = client([{ tool: 'query_graph', recording: 'env-reads' }]);
        const rows = await c.queryRows(RECORDED_PROJECT, 'MATCH ...');
        // Der Server schreibt hier `-`; mit `format: "json"` schreibt er an
        // derselben Stelle "". Ein Bindestrich als Dateiname waere eine
        // Erfindung dieser Schicht.
        expect(rows[0]['b.file_path']).toBe('');
        expect(rows[0]['r.line']).toBe('');
        expect(rows[0]['b.env_key']).toBe('DB_URL');
    });

    it('benennt die Zeilen nach den Spalten, die die Abfrage verlangt hat', async () => {
        const { client: c } = client([{ tool: 'query_graph', recording: 'calls-in' }]);
        const rows = await c.queryRows(RECORDED_PROJECT, 'MATCH ...');
        expect(rows[0]['a.is_test']).toBe('true');
        expect(rows[0]['a.file_path']).toBe('test/userService.test.ts');
    });

    it('fragt query_graph ohne format, weil die kompakte Form die Vorgabe ist', async () => {
        const { client: c, rpc } = client([{ tool: 'query_graph', recording: 'calls-out' }]);
        await c.queryGraph(RECORDED_PROJECT, 'MATCH ...');
        expect(rpc.calls[0].args['format']).toBeUndefined();
    });

    it('meldet eine unlesbare Antwort als Engine-Fehler, nicht als leere Tabelle', async () => {
        const { client: c } = client([{ tool: 'query_graph', text: 'nodes: 3\n  a\n' }]);
        await expect(c.queryGraph(RECORDED_PROJECT, 'MATCH ...')).rejects.toBeInstanceOf(EngineError);
    });
});

describe('die Werkzeuge, die von sich aus JSON liefern', () => {

    it('liest die Projektliste mit ihrer Wurzel', async () => {
        const { client: c } = client([listProjectsRoute()]);
        const result = await c.listProjects();
        expect(result.projects).toHaveLength(1);
        expect(result.projects[0].name).toBe(RECORDED_PROJECT);
        expect(result.projects[0].root_path).toContain('fixtures/atlas-sample');
    });

    it('loads every project page instead of silently returning the first page', async () => {
        const first = Array.from({ length: 500 }, (_, index) => ({ name: `project-${index}` }));
        const { client: c, rpc } = client([
            { tool: 'list_projects', when: args => args.offset === 0, json: { projects: first, total: 501, offset: 0, limit: 500, returned: 500, has_more: true, next_offset: 500 } },
            { tool: 'list_projects', when: args => args.offset === 500, json: { projects: [{ name: 'project-500' }], total: 501, offset: 500, limit: 500, returned: 1, has_more: false } },
        ]);
        const result = await c.listProjects();
        expect(result.projects).toHaveLength(501);
        expect(result.projects.at(-1)?.name).toBe('project-500');
        expect(rpc.calls.map(call => call.args)).toEqual([{ limit: 500, offset: 0, format: 'json' }, { limit: 500, offset: 500, format: 'json' }]);
    });

    it.each([
        { projects: [{ name: 'a' }], total: 2, returned: 1, offset: 0, has_more: true, next_offset: 0 },
        { projects: [{ name: 'a' }], total: 2, returned: 1, offset: 0, has_more: false },
        { projects: [], total: 2, returned: 0, offset: 0, has_more: true, next_offset: 1 },
        { projects: [{ name: 'a' }], returned: 2, offset: 0, has_more: false },
        { projects: [{ name: 'a' }], has_more: 'true' },
    ])('refuses incomplete or inconsistent project pagination %#', async json => {
        const { client: c, rpc } = client([{ tool: 'list_projects', json }]);
        await expect(c.listProjects()).rejects.toBeInstanceOf(EngineError);
        expect(rpc.calls).toHaveLength(1);
    });

    it('rejects repeated projects and changed totals across pages', async () => {
        for (const page of [
            { projects: [{ name: 'a' }], total: 2, returned: 1, offset: 1, has_more: false },
            { projects: [{ name: 'b' }], total: 3, returned: 1, offset: 1, has_more: true, next_offset: 2 },
        ]) {
            const { client: c } = client([
                { tool: 'list_projects', when: args => args.offset === 0, json: { projects: [{ name: 'a' }], total: 2, returned: 1, offset: 0, has_more: true, next_offset: 1 } },
                { tool: 'list_projects', when: args => args.offset === 1, json: page },
            ]);
            await expect(c.listProjects()).rejects.toBeInstanceOf(EngineError);
        }
    });

    it('liest den Quelltext eines Symbols samt Spanne', async () => {
        const { client: c } = client([{
            tool: 'get_code_snippet',
            json: {
                name: 'createUser',
                qualified_name: `${RECORDED_PROJECT}.src.services.userService.createUser`,
                label: 'Function',
                file_path: '/tmp/atlas-sample/src/services/userService.ts',
                start_line: 23,
                end_line: 36,
                source: 'export function createUser(input: unknown): User {\n}\n',
                callers: 2,
                callees: 6,
            },
        }]);
        const snippet = await c.getCodeSnippet(RECORDED_PROJECT, 'x');
        expect(snippet.start_line).toBe(23);
        expect(snippet.end_line).toBe(36);
        expect(snippet.source).toContain('export function createUser');
    });

    it('bittet um vollen Quelltext, seit der Server Container sonst nur umreisst', async () => {
        const { client: c, rpc } = client([{
            tool: 'get_code_snippet',
            json: { start_line: 1, end_line: 500, source: 'x\n', next_start_line: 501, original_end_line: 900, source_mode: 'full' },
        }]);
        const page = await c.getCodeSnippet(RECORDED_PROJECT, 'x', { startLine: 1, maxLines: 500 });
        expect(page.next_start_line).toBe(501);
        expect(page.original_end_line).toBe(900);
        expect(page.source_mode).toBe('full');
        expect(rpc.callsTo('get_code_snippet')[0]?.args).toMatchObject({ source_mode: 'full', start_line: 1, max_lines: 500 });
    });

    it('liest den Indexzustand', async () => {
        const { client: c } = client([{
            tool: 'index_status',
            json: { project: RECORDED_PROJECT, nodes: 76, edges: 178, status: 'ready' },
        }]);
        const status = await c.indexStatus(RECORDED_PROJECT);
        expect(status.status).toBe('ready');
        expect(status.nodes).toBe(76);
    });

    it('reicht die Coverage-Beilage ungedeutet weiter', async () => {
        // Die Beilage wird im Join des Explorers gelesen. Dass sie hier
        // unangetastet ankommt, ist die Bedingung dafuer.
        const payload = {
            project: RECORDED_PROJECT,
            nodes: 76,
            parse_partial: { files: [{ path: 'src/a.ts', error_ranges: '4-9' }], count: 1, truncated: false },
        };
        const { client: c } = client([{ tool: 'index_status', json: payload }]);
        expect(await c.indexStatusPayload(RECORDED_PROJECT)).toEqual(payload);
    });

    it('fragt den Coverage-Store nach Pfaden und schreibt die Argumente so, wie er sie kennt', async () => {
        const { client: c, rpc } = client([{ tool: 'check_index_coverage', json: { paths: [] } }]);
        await c.checkIndexCoverage(RECORDED_PROJECT, { paths: ['src/a.ts'] });
        expect(rpc.calls[0].args['paths']).toEqual(['src/a.ts']);
        expect(rpc.calls[0].args['scopes']).toBeUndefined();
        expect(rpc.calls[0].args['scope_limit']).toBeUndefined();
    });

    it('fragt ihn nach Scopes mit Seitengrenze und Versatz', async () => {
        const { client: c, rpc } = client([{ tool: 'check_index_coverage', json: { scopes: [] } }]);
        await c.checkIndexCoverage(RECORDED_PROJECT, {
            scopes: ['.'],
            scopeLimit: 1000,
            scopeOffset: 200,
        });
        expect(rpc.calls[0].args['scopes']).toEqual(['.']);
        expect(rpc.calls[0].args['scope_limit']).toBe(1000);
        expect(rpc.calls[0].args['scope_offset']).toBe(200);
    });

    it('meldet einen gesperrten Coverage-Aufruf als nicht angebotene Faehigkeit', async () => {
        const { client: c } = client([{ tool: 'check_index_coverage', notAllowed: true }]);
        await expect(c.checkIndexCoverage(RECORDED_PROJECT, { scopes: ['.'] }))
            .rejects.toBeInstanceOf(EngineUnavailableError);
    });
});

describe('die Werkzeuge, die erst auf Bitte JSON liefern', () => {

    it('bittet um format json, statt eine Anzeigeform zu parsen', async () => {
        const { client: c, rpc } = client([{ tool: 'index_status', json: { status: 'ready' } }]);
        await c.indexStatus(RECORDED_PROJECT);
        expect(rpc.calls[0].args['format']).toBe('json');
    });

    it('flacht den gruppierten Pfadlauf zu Hops mit qualifizierten Namen ab', async () => {
        const { client: c } = client([{
            tool: 'trace_path',
            json: {
                function: 'createUser',
                direction: 'both',
                callees_total: 7,
                callees: {
                    cols: ['name', 'hop'],
                    groups: [
                        { qn_prefix: `${RECORDED_PROJECT}.src.types`, rows: [['UserEntity', 1]] },
                        { qn_prefix: `${RECORDED_PROJECT}.src.repo.db`, rows: [['insert', 1], ['query', 2]] },
                    ],
                },
                callers_total: 1,
                callers: {
                    cols: ['name', 'hop'],
                    groups: [
                        { qn_prefix: `${RECORDED_PROJECT}.src.routes.users`, rows: [['registerUserRoutes', 1]] },
                    ],
                },
            },
        }]);
        const result = await c.tracePath(RECORDED_PROJECT, 'createUser');
        expect(isAmbiguousPath(result)).toBe(false);
        if (isAmbiguousPath(result)) {
            return;
        }
        expect(result.callees?.map((hop) => hop.qualified_name)).toEqual([
            `${RECORDED_PROJECT}.src.types.UserEntity`,
            `${RECORDED_PROJECT}.src.repo.db.insert`,
            `${RECORDED_PROJECT}.src.repo.db.query`,
        ]);
        expect(result.callees?.[2].hop).toBe(2);
        expect(result.callers).toHaveLength(1);
    });

    it('spricht Richtung und Tiefe in den Woertern des trace_path-Schemas', async () => {
        const { client: c, rpc } = client([{ tool: 'trace_path', json: { function: 'createUser', direction: 'inbound' } }]);
        await c.tracePath(RECORDED_PROJECT, 'createUser', { direction: 'inbound', depth: 2 });
        expect(rpc.calls[0].args).toMatchObject({ function_name: 'createUser', direction: 'inbound', depth: 2 });
        expect(rpc.calls[0].args).not.toHaveProperty('max_depth');
        await c.tracePath(RECORDED_PROJECT, 'createUser');
        expect(rpc.calls[1].args).not.toHaveProperty('direction');
        expect(rpc.calls[1].args).not.toHaveProperty('depth');
    });

    it('gibt die Ablehnung wegen Mehrdeutigkeit als Antwort weiter, nicht als Fehler', async () => {
        const { client: c } = client([{
            tool: 'trace_path',
            json: {
                status: 'ambiguous',
                message: '2 matches for "create".',
                suggestions: [
                    { qualified_name: `${RECORDED_PROJECT}.src.services.orderService.create`, name: 'create', label: 'Function', file_path: 'src/services/orderService.ts' },
                    { qualified_name: `${RECORDED_PROJECT}.src.services.userService.create`, name: 'create', label: 'Function', file_path: 'src/services/userService.ts' },
                ],
            },
        }]);
        const result = await c.tracePath(RECORDED_PROJECT, 'create');
        expect(isAmbiguousPath(result)).toBe(true);
        if (!isAmbiguousPath(result)) {
            return;
        }
        expect(result.suggestions).toHaveLength(2);
        expect(result.suggestions[0].file_path).toBe('src/services/orderService.ts');
    });

    it('bringt die Aspekte der Uebersicht auf die Form, die der Provider liest', async () => {
        const { client: c } = client([{
            tool: 'get_architecture',
            json: {
                project: RECORDED_PROJECT,
                total_nodes: 76,
                total_edges: 178,
                node_labels: { cols: ['label', 'count'], rows: [['Function', 18], ['File', 11]] },
                languages: { cols: ['language', 'files'], rows: [['TypeScript', 10]] },
                packages: { cols: ['name', 'nodes', 'fan_in', 'fan_out'], rows: [['services', 6, 0, 0]] },
                entry_points: { cols: ['qn', 'file'], rows: [[`${RECORDED_PROJECT}.src.server.main`, 'src/server.ts']] },
                boundaries: { cols: ['from', 'to', 'calls'], rows: [['services', 'repo', 4]] },
                file_tree: { cols: ['path', 'type', 'children'], rows: [['src', 'dir', 7], ['src/types.ts', 'file', 0]] },
            },
        }]);
        const overview = await c.getArchitecture(RECORDED_PROJECT);
        expect(overview.total_nodes).toBe(76);
        expect(overview.node_labels[0]).toEqual({ label: 'Function', count: 18 });
        // Der Server sagt `files`, `nodes` und `calls`; der Provider liest
        // `file_count`, `node_count` und `call_count`. Umbenannt wird hier.
        expect(overview.languages[0]).toEqual({ language: 'TypeScript', file_count: 10 });
        expect(overview.packages[0].node_count).toBe(6);
        expect(overview.boundaries[0].call_count).toBe(4);
        expect(overview.entry_points[0]).toEqual({
            name: 'main',
            qualified_name: `${RECORDED_PROJECT}.src.server.main`,
            file: 'src/server.ts',
        });
        // Kein routes-Schluessel fuer TypeScript: leer, und die Faehigkeit
        // sagt, dass leer hier nicht "es gibt keine" heisst.
        expect(overview.routes).toEqual([]);
        expect(overview.file_tree).toHaveLength(2);
    });

    it('liest die Aenderungsmenge unter beiden Schreibweisen der Symbolliste', async () => {
        const { client: c } = client([{
            tool: 'detect_changes',
            json: {
                base: 'main',
                changed_files: ['src/services/userService.ts'],
                impacted: {
                    cols: ['name', 'label', 'hop'],
                    groups: [{ qn_prefix: `${RECORDED_PROJECT}.src.services.userService`, file: 'src/services/userService.ts', rows: [['createUser', 'Function', 0]] }],
                },
            },
        }]);
        const changes = await c.detectChanges(RECORDED_PROJECT, 'main');
        expect(changes.changed_files).toEqual(['src/services/userService.ts']);
        expect(changes.impacted_symbols).toHaveLength(1);
        expect(changes.impacted_symbols[0].qualified_name)
            .toBe(`${RECORDED_PROJECT}.src.services.userService.createUser`);
        expect(changes.impacted_symbols[0].file).toBe('src/services/userService.ts');
    });

    it('schickt den Vergleichspunkt als since, so wie das Werkzeug ihn deklariert', async () => {
        const { client: c, rpc } = client([{ tool: 'detect_changes', json: { changed_files: [] } }]);
        await c.detectChanges(RECORDED_PROJECT, 'HEAD~3', { depth: 2 });
        expect(rpc.calls[0].args['since']).toBe('HEAD~3');
        expect(rpc.calls[0].args['depth']).toBe(2);
    });

    it('vergleicht den Working tree explizit mit HEAD, auch ohne lokalen main-Branch', async () => {
        const { client: c, rpc } = client([{ tool: 'detect_changes', json: { changed_files: [] } }]);
        await c.detectChanges(RECORDED_PROJECT);
        expect(rpc.calls[0].args['since']).toBe('HEAD');
    });
});

describe('Suche', () => {

    it('liest die flache Suchform mit Rang', async () => {
        const { client: c } = client([{ tool: 'search_graph', recording: 'search' }]);
        const result = await c.searchGraph(RECORDED_PROJECT, { namePattern: 'createUser', limit: 5 });
        expect(result.total).toBe(1);
        expect(result.results).toHaveLength(1);
        expect(result.results[0].name).toBe('createUser');
        expect(result.results[0].qualified_name)
            .toBe(`${RECORDED_PROJECT}.src.services.userService.createUser`);
        expect(result.results[0].file_path).toBe('src/services/userService.ts');
        // `lines` ist eine Spanne "23-36"; die Deklarationszeile ist ihr Anfang.
        expect(result.results[0].start_line).toBe(23);
    });

    it('behauptet nicht, was die Suchantwort nicht sagt', async () => {
        const { client: c } = client([{ tool: 'search_graph', recording: 'search' }]);
        const result = await c.searchGraph(RECORDED_PROJECT, { namePattern: 'createUser' });
        expect(result.results[0].is_test).toBeUndefined();
        expect(result.results[0].is_exported).toBeUndefined();
    });
});

describe('was schiefgehen kann', () => {

    it('macht aus einem stummen Server einen nicht erreichbaren, nicht aus einem leeren Ergebnis', async () => {
        const { client: c } = client([{ tool: 'list_projects', networkError: 'fetch failed' }]);
        await expect(c.listProjects()).rejects.toBeInstanceOf(EngineUnavailableError);
    });

    it('macht aus der Ablehnung der Allowlist einen nicht erreichbaren Server, keinen Engine-Fehler', async () => {
        const { client: c } = client([{ tool: 'get_architecture', notAllowed: true }]);
        await expect(c.getArchitecture(RECORDED_PROJECT)).rejects.toBeInstanceOf(EngineUnavailableError);
    });

    it('macht aus einem inhaltlichen Nein des Werkzeugs einen Engine-Fehler', async () => {
        const { client: c } = client([{ tool: 'get_code_snippet', toolError: 'Symbol not found: x' }]);
        await expect(c.getCodeSnippet(RECORDED_PROJECT, 'x')).rejects.toBeInstanceOf(EngineError);
    });

    it('lehnt die drei schreibenden Werkzeuge ab, ohne sie ueberhaupt zu fragen', async () => {
        const { client: c, rpc } = client([]);
        await expect(c.indexRepository()).rejects.toBeInstanceOf(EngineUnavailableError);
        await expect(c.deleteProject()).rejects.toBeInstanceOf(EngineUnavailableError);
        await expect(c.ingestTraces()).rejects.toBeInstanceOf(EngineUnavailableError);
        expect(rpc.calls).toEqual([]);
    });

    it('nennt in der Ablehnung, wo der schreibende Weg stattdessen laeuft', async () => {
        const { client: c } = client([]);
        await expect(c.ingestTraces()).rejects.toThrow(/CLI/);
    });

    it('liest eine leere Tabelle als leer und nicht als Fehler', async () => {
        const { client: c } = client([{ tool: 'query_graph', text: rowsText(['n.name'], []) }]);
        const result = await c.queryGraph(RECORDED_PROJECT, 'MATCH ...');
        expect(result.rows).toEqual([]);
        expect(result.total).toBe(0);
    });
});