@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.10

package/dist/tools/lsp-tools.js

@@ -1,565 +0,0 @@
-import { callHierarchyAt, codeActionsAt, diagnosticsFor, findDefinition as symbolsFindDefinition, findImplementations, findReferences as symbolsFindReferences, findTypeDefinition, findWorkspaceSymbol, formatFile, hoverSymbol, listDocumentSymbols, renameSymbol, signatureAt, transportFromLspClient, } from '../core/lsp/symbol-tools.js';
-import { gateOnCancellation, OperatorAbortedError } from './file-tools.js';
-import { recordToolCall, recordToolResult } from '../core/session.js';
-import { getGlobalSymbolCache, SymbolCache } from '../core/lsp/symbol-cache.js';
-/** Cap for any single LSP tool's payload size. Keeps model context lean. */
-const LSP_PAYLOAD_CAP_BYTES = 8 * 1024;
-export async function lspHover(ctx, lang, file, line, col) {
-    const toolCallId = recordToolCall(ctx.session, 'lsp_hover', `${lang}:${file}:${line}:${col}`);
-    return guard(ctx, 'lsp_hover', toolCallId, async () => {
-        const client = ctx.lspClients?.get(lang);
-        if (!client)
-            return unavailable(lang);
-        const result = await client.hover(file, { line, character: col }, ctx.cancellation);
-        if (!result.ok)
-            return failure(result);
-        if (!result.value) {
-            return { ok: true, value: { content: '' } };
-        }
-        const content = truncate(result.value.content);
-        return {
-            ok: true,
-            value: {
-                content: content.text,
-                ...(result.value.range ? { range: result.value.range } : {}),
-            },
-            ...(content.truncated ? { truncated: true } : {}),
-        };
-    });
-}
-export async function lspDefinition(ctx, lang, file, line, col) {
-    const toolCallId = recordToolCall(ctx.session, 'lsp_definition', `${lang}:${file}:${line}:${col}`);
-    return guard(ctx, 'lsp_definition', toolCallId, async () => {
-        const client = ctx.lspClients?.get(lang);
-        if (!client)
-            return unavailable(lang);
-        const result = await client.definition(file, { line, character: col }, ctx.cancellation);
-        if (!result.ok)
-            return failure(result);
-        const capped = capLocations(result.value);
-        return {
-            ok: true,
-            value: capped.value,
-            ...(capped.truncated ? { truncated: true } : {}),
-        };
-    });
-}
-export async function lspReferences(ctx, lang, file, line, col) {
-    const toolCallId = recordToolCall(ctx.session, 'lsp_references', `${lang}:${file}:${line}:${col}`);
-    return guard(ctx, 'lsp_references', toolCallId, async () => {
-        const client = ctx.lspClients?.get(lang);
-        if (!client)
-            return unavailable(lang);
-        const result = await client.references(file, { line, character: col }, ctx.cancellation);
-        if (!result.ok)
-            return failure(result);
-        const capped = capLocations(result.value);
-        return {
-            ok: true,
-            value: capped.value,
-            ...(capped.truncated ? { truncated: true } : {}),
-        };
-    });
-}
-export async function lspDiagnostics(ctx, lang, file) {
-    const toolCallId = recordToolCall(ctx.session, 'lsp_diagnostics', `${lang}:${file}`);
-    return guard(ctx, 'lsp_diagnostics', toolCallId, async () => {
-        const client = ctx.lspClients?.get(lang);
-        if (!client)
-            return unavailable(lang);
-        const result = await client.diagnostics(file, ctx.cancellation);
-        if (!result.ok)
-            return failure(result);
-        const capped = capDiagnostics(result.value);
-        return {
-            ok: true,
-            value: capped.value,
-            ...(capped.truncated ? { truncated: true } : {}),
-        };
-    });
-}
-async function guard(ctx, toolName, toolCallId, op) {
-    try {
-        gateOnCancellation(ctx, toolName);
-    }
-    catch (error) {
-        if (error instanceof OperatorAbortedError) {
-            recordToolResult(ctx.session, toolCallId, 'cancelled', error.message);
-            return { ok: false, reason: 'operator_aborted', detail: error.message };
-        }
-        throw error;
-    }
-    try {
-        const result = await op();
-        if (result.ok) {
-            recordToolResult(ctx.session, toolCallId, 'success', summarize(result.value));
-        }
-        else {
-            recordToolResult(ctx.session, toolCallId, 'error', `${result.reason ?? 'error'}: ${result.detail ?? ''}`);
-        }
-        return result;
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        recordToolResult(ctx.session, toolCallId, 'error', message);
-        return { ok: false, reason: 'lsp_error', detail: message };
-    }
-}
-function unavailable(lang) {
-    return {
-        ok: false,
-        reason: 'lsp_unavailable',
-        detail: `no LSP server started for ${lang}. Install the server and re-run ` +
-            `with --lsp ${lang}, or fall back to grep.`,
-    };
-}
-function failure(result) {
-    if (result.ok) {
-        // Shouldn't be hit — caller checks first.
-        return { ok: true, value: result.value };
-    }
-    return { ok: false, reason: result.reason, detail: result.detail };
-}
-function summarize(value) {
-    if (value === null || value === undefined)
-        return 'no result';
-    if (Array.isArray(value))
-        return `${value.length} items`;
-    if (typeof value === 'object')
-        return Object.keys(value).join(',');
-    return String(value);
-}
-function truncate(text) {
-    const bytes = Buffer.byteLength(text, 'utf8');
-    if (bytes <= LSP_PAYLOAD_CAP_BYTES)
-        return { text, truncated: false };
-    // Truncate to the cap byte boundary. We don't try to honor codepoint
-    // alignment — UTF-8 surrogate splits show up as a single ? at the
-    // boundary, which is acceptable for a debug surface; the dispatcher
-    // is the trust boundary for "this is what the model will see".
-    const buf = Buffer.from(text, 'utf8').subarray(0, LSP_PAYLOAD_CAP_BYTES);
-    return { text: `${buf.toString('utf8')}\n... [truncated]`, truncated: true };
-}
-function capLocations(locations) {
-    // Cap at 200 locations OR the byte cap, whichever hits first. The
-    // 200 number is the operator-facing "this is a hot symbol" threshold —
-    // a richer surface (paginated `pugi lsp references --offset N`) is
-    // open backlog.
-    const COUNT_CAP = 200;
-    if (locations.length === 0)
-        return { value: locations, truncated: false };
-    const trimmed = locations.slice(0, COUNT_CAP);
-    const serialized = JSON.stringify(trimmed);
-    if (Buffer.byteLength(serialized, 'utf8') <= LSP_PAYLOAD_CAP_BYTES && trimmed.length === locations.length) {
-        return { value: trimmed, truncated: false };
-    }
-    // Trim by halves until we fit the byte cap. Worst case ~10 iterations
-    // for the 200 max, fine for an interactive tool.
-    let upper = trimmed.length;
-    while (upper > 1) {
-        const half = Math.floor(upper / 2);
-        const sub = trimmed.slice(0, half);
-        if (Buffer.byteLength(JSON.stringify(sub), 'utf8') <= LSP_PAYLOAD_CAP_BYTES) {
-            return { value: sub, truncated: true };
-        }
-        upper = half;
-    }
-    return { value: trimmed.slice(0, 1), truncated: true };
-}
-function capDiagnostics(items) {
-    if (items.length === 0)
-        return { value: items, truncated: false };
-    const serialized = JSON.stringify(items);
-    if (Buffer.byteLength(serialized, 'utf8') <= LSP_PAYLOAD_CAP_BYTES) {
-        return { value: items, truncated: false };
-    }
-    // Diagnostics are sorted error-first in LSP convention; trim from the
-    // tail so we keep the highest-severity items.
-    let upper = items.length;
-    while (upper > 1) {
-        const half = Math.floor(upper / 2);
-        const sub = items.slice(0, half);
-        if (Buffer.byteLength(JSON.stringify(sub), 'utf8') <= LSP_PAYLOAD_CAP_BYTES) {
-            return { value: sub, truncated: true };
-        }
-        upper = half;
-    }
-    return { value: items.slice(0, 1), truncated: true };
-}
-/* ------------------------------------------------------------------------- */
-/* PUGI-78 Phase 1: symbols.* namespace tools (13 categories).               */
-/* ------------------------------------------------------------------------- */
-/**
- * PUGI-78 Phase 1: symbols.find_definition.
- *
- * Pugi reads a whole file (~5-50 KB tokens) every time the model wants
- * to know "where is foo defined?". The LSP wire here returns ~200 bytes
- * (file + line + character). Two orders of magnitude reduction in token
- * cost per refactor turn, hence the BIG-leverage classification in the
- * spec (10-100x token savings per refactor).
- *
- * Failure folds to `lsp_unavailable` when no client is registered for
- * the inferred language. The agent surface is expected to fall back to
- * grep when this fires (the tool-preference prompt rule steers it).
- */
-export async function symbolsFindDefinitionTool(ctx, lang, file, line, col) {
-    const toolCallId = recordToolCall(ctx.session, 'symbols_find_definition', `${lang}:${file}:${line}:${col}`);
-    return guard(ctx, 'symbols_find_definition', toolCallId, async () => {
-        const client = ctx.lspClients?.get(lang);
-        if (!client)
-            return unavailable(lang);
-        const cache = getSymbolCacheFromCtx(ctx);
-        const cwd = workspaceForCache(ctx);
-        const key = SymbolCache.makeKey(lang, cwd, 'find_definition', { file, line, col });
-        const cached = cache?.get(key);
-        if (cached !== undefined) {
-            if (cached === null)
-                return notFound('definition');
-            return { ok: true, value: cached };
-        }
-        const result = await symbolsFindDefinition(transportFromLspClient(client), file, line, col);
-        cache?.set(key, result);
-        if (!result)
-            return notFound('definition');
-        return { ok: true, value: result };
-    });
-}
-/**
- * PUGI-78 Phase 1: symbols.find_references.
- *
- * Returns the flat list of call sites for the symbol at (line, col).
- * The 200-row cap from the legacy `lspReferences` carries over via
- * `capSymbolReferences`.
- */
-export async function symbolsFindReferencesTool(ctx, lang, file, line, col) {
-    const toolCallId = recordToolCall(ctx.session, 'symbols_find_references', `${lang}:${file}:${line}:${col}`);
-    return guard(ctx, 'symbols_find_references', toolCallId, async () => {
-        const client = ctx.lspClients?.get(lang);
-        if (!client)
-            return unavailable(lang);
-        const cache = getSymbolCacheFromCtx(ctx);
-        const cwd = workspaceForCache(ctx);
-        const key = SymbolCache.makeKey(lang, cwd, 'find_references', { file, line, col });
-        const cached = cache?.get(key);
-        if (cached !== undefined) {
-            const capped = capSymbolReferences(cached);
-            return { ok: true, value: capped.value, ...(capped.truncated ? { truncated: true } : {}) };
-        }
-        const result = await symbolsFindReferences(transportFromLspClient(client), file, line, col);
-        cache?.set(key, result);
-        const capped = capSymbolReferences(result);
-        return { ok: true, value: capped.value, ...(capped.truncated ? { truncated: true } : {}) };
-    });
-}
-/**
- * PUGI-78 Phase 1: symbols.list_in_file.
- *
- * Outline view — the document-symbol surface. Returns the flat list of
- * top-level + nested symbols with their kind. Cache HIT on the same
- * file across consecutive turns is the common case (the model usually
- * lists, then dives into a single symbol).
- */
-export async function symbolsListInFileTool(ctx, lang, file) {
-    const toolCallId = recordToolCall(ctx.session, 'symbols_list_in_file', `${lang}:${file}`);
-    return guard(ctx, 'symbols_list_in_file', toolCallId, async () => {
-        const client = ctx.lspClients?.get(lang);
-        if (!client)
-            return unavailable(lang);
-        const cache = getSymbolCacheFromCtx(ctx);
-        const cwd = workspaceForCache(ctx);
-        const key = SymbolCache.makeKey(lang, cwd, 'list_in_file', { file });
-        const cached = cache?.get(key);
-        if (cached !== undefined) {
-            return { ok: true, value: [...cached] };
-        }
-        const result = await listDocumentSymbols(transportFromLspClient(client), file);
-        cache?.set(key, result);
-        return { ok: true, value: result };
-    });
-}
-/**
- * PUGI-78 Phase 1: symbols.rename.
- *
- * Returns the workspace-edit preview the server proposes. The
- * dispatcher applies via `apply_patch` in a future ticket; Phase 1 is
- * read-only — the agent surface gets the affected file list + per-edit
- * line/character so the model can summarize the change.
- */
-export async function symbolsRenameTool(ctx, lang, file, line, col, newName) {
-    const toolCallId = recordToolCall(ctx.session, 'symbols_rename', `${lang}:${file}:${line}:${col}:${newName}`);
-    return guard(ctx, 'symbols_rename', toolCallId, async () => {
-        const client = ctx.lspClients?.get(lang);
-        if (!client)
-            return unavailable(lang);
-        // No cache for rename — the edit set depends on the live source
-        // file state. A subsequent rename of the same symbol after the
-        // first applied would otherwise return stale edits.
-        const result = await renameSymbol(transportFromLspClient(client), file, line, col, newName);
-        if (!result)
-            return notFound('rename');
-        return { ok: true, value: result };
-    });
-}
-/**
- * PUGI-78 Phase 1: symbols.hover.
- *
- * Returns the hover content (type info + docstring) at the position.
- * Body capped at 4 KB so a verbose generic does not blow context.
- */
-export async function symbolsHoverTool(ctx, lang, file, line, col) {
-    const toolCallId = recordToolCall(ctx.session, 'symbols_hover', `${lang}:${file}:${line}:${col}`);
-    return guard(ctx, 'symbols_hover', toolCallId, async () => {
-        const client = ctx.lspClients?.get(lang);
-        if (!client)
-            return unavailable(lang);
-        const cache = getSymbolCacheFromCtx(ctx);
-        const cwd = workspaceForCache(ctx);
-        const key = SymbolCache.makeKey(lang, cwd, 'hover', { file, line, col });
-        const cached = cache?.get(key);
-        if (cached !== undefined) {
-            if (cached === null)
-                return notFound('hover');
-            const next = {
-                ok: true,
-                value: { content: cached.content, ...(cached.range ? { range: cached.range } : {}) },
-                ...(cached.truncated ? { truncated: true } : {}),
-            };
-            return next;
-        }
-        const result = await hoverSymbol(transportFromLspClient(client), file, line, col);
-        cache?.set(key, result);
-        if (!result)
-            return notFound('hover');
-        return {
-            ok: true,
-            value: { content: result.content, ...(result.range ? { range: result.range } : {}) },
-            ...(result.truncated ? { truncated: true } : {}),
-        };
-    });
-}
-/**
- * PUGI-78 Phase 1: symbols.signature.
- *
- * Function signature at a call site. Returns the active overload's
- * label, parameters, and active-parameter index.
- */
-export async function symbolsSignatureTool(ctx, lang, file, line, col) {
-    const toolCallId = recordToolCall(ctx.session, 'symbols_signature', `${lang}:${file}:${line}:${col}`);
-    return guard(ctx, 'symbols_signature', toolCallId, async () => {
-        const client = ctx.lspClients?.get(lang);
-        if (!client)
-            return unavailable(lang);
-        const result = await signatureAt(transportFromLspClient(client), file, line, col);
-        if (!result)
-            return notFound('signature');
-        return { ok: true, value: result };
-    });
-}
-/**
- * PUGI-78 Phase 1: symbols.workspace_symbols.
- *
- * Workspace-wide fuzzy search. The server picks the matching algorithm
- * (substring / fuzzy / prefix); we forward verbatim.
- */
-export async function symbolsWorkspaceSymbolsTool(ctx, lang, query) {
-    const toolCallId = recordToolCall(ctx.session, 'symbols_workspace_symbols', `${lang}:${query}`);
-    return guard(ctx, 'symbols_workspace_symbols', toolCallId, async () => {
-        const client = ctx.lspClients?.get(lang);
-        if (!client)
-            return unavailable(lang);
-        const cache = getSymbolCacheFromCtx(ctx);
-        const cwd = workspaceForCache(ctx);
-        const key = SymbolCache.makeKey(lang, cwd, 'workspace_symbols', { query });
-        const cached = cache?.get(key);
-        if (cached !== undefined) {
-            return { ok: true, value: [...cached] };
-        }
-        const result = await findWorkspaceSymbol(transportFromLspClient(client), query);
-        cache?.set(key, result);
-        return { ok: true, value: result };
-    });
-}
-/**
- * PUGI-78 Phase 1: symbols.call_hierarchy.
- *
- * Returns the incoming + outgoing call edges at the symbol position.
- * The two arrays are independent — a function may have many incoming
- * callers and zero outgoing calls (a pure leaf), or vice versa.
- */
-export async function symbolsCallHierarchyTool(ctx, lang, file, line, col) {
-    const toolCallId = recordToolCall(ctx.session, 'symbols_call_hierarchy', `${lang}:${file}:${line}:${col}`);
-    return guard(ctx, 'symbols_call_hierarchy', toolCallId, async () => {
-        const client = ctx.lspClients?.get(lang);
-        if (!client)
-            return unavailable(lang);
-        const cache = getSymbolCacheFromCtx(ctx);
-        const cwd = workspaceForCache(ctx);
-        const key = SymbolCache.makeKey(lang, cwd, 'call_hierarchy', { file, line, col });
-        const cached = cache?.get(key);
-        if (cached !== undefined) {
-            return { ok: true, value: { incoming: [...cached.incoming], outgoing: [...cached.outgoing] } };
-        }
-        const result = await callHierarchyAt(transportFromLspClient(client), file, line, col);
-        cache?.set(key, result);
-        return { ok: true, value: result };
-    });
-}
-/**
- * PUGI-78 Phase 1: symbols.implementations.
- *
- * Implementations of an interface / abstract method. Returns the flat
- * list of concrete sites.
- */
-export async function symbolsImplementationsTool(ctx, lang, file, line, col) {
-    const toolCallId = recordToolCall(ctx.session, 'symbols_implementations', `${lang}:${file}:${line}:${col}`);
-    return guard(ctx, 'symbols_implementations', toolCallId, async () => {
-        const client = ctx.lspClients?.get(lang);
-        if (!client)
-            return unavailable(lang);
-        const cache = getSymbolCacheFromCtx(ctx);
-        const cwd = workspaceForCache(ctx);
-        const key = SymbolCache.makeKey(lang, cwd, 'implementations', { file, line, col });
-        const cached = cache?.get(key);
-        if (cached !== undefined) {
-            const capped = capSymbolReferences(cached);
-            return { ok: true, value: capped.value, ...(capped.truncated ? { truncated: true } : {}) };
-        }
-        const result = await findImplementations(transportFromLspClient(client), file, line, col);
-        cache?.set(key, result);
-        const capped = capSymbolReferences(result);
-        return { ok: true, value: capped.value, ...(capped.truncated ? { truncated: true } : {}) };
-    });
-}
-/**
- * PUGI-78 Phase 1: symbols.type_definition.
- *
- * Type definition (vs value definition). Useful for "what type is foo?"
- * questions when the model has a variable and wants its type declaration.
- */
-export async function symbolsTypeDefinitionTool(ctx, lang, file, line, col) {
-    const toolCallId = recordToolCall(ctx.session, 'symbols_type_definition', `${lang}:${file}:${line}:${col}`);
-    return guard(ctx, 'symbols_type_definition', toolCallId, async () => {
-        const client = ctx.lspClients?.get(lang);
-        if (!client)
-            return unavailable(lang);
-        const cache = getSymbolCacheFromCtx(ctx);
-        const cwd = workspaceForCache(ctx);
-        const key = SymbolCache.makeKey(lang, cwd, 'type_definition', { file, line, col });
-        const cached = cache?.get(key);
-        if (cached !== undefined) {
-            if (cached === null)
-                return notFound('type_definition');
-            return { ok: true, value: cached };
-        }
-        const result = await findTypeDefinition(transportFromLspClient(client), file, line, col);
-        cache?.set(key, result);
-        if (!result)
-            return notFound('type_definition');
-        return { ok: true, value: result };
-    });
-}
-/**
- * PUGI-78 Phase 1: symbols.code_actions.
- *
- * Quick-fix list at the given range. Server-provided actions include
- * auto-import, unused-import removal, refactor extractions, etc.
- */
-export async function symbolsCodeActionsTool(ctx, lang, file, startLine, startChar, endLine, endChar) {
-    const toolCallId = recordToolCall(ctx.session, 'symbols_code_actions', `${lang}:${file}:${startLine}:${startChar}-${endLine}:${endChar}`);
-    return guard(ctx, 'symbols_code_actions', toolCallId, async () => {
-        const client = ctx.lspClients?.get(lang);
-        if (!client)
-            return unavailable(lang);
-        const result = await codeActionsAt(transportFromLspClient(client), file, startLine, startChar, endLine, endChar);
-        return { ok: true, value: result };
-    });
-}
-/**
- * PUGI-78 Phase 1: symbols.format.
- *
- * Formatter — returns the text edits the LSP server would apply for
- * `textDocument/formatting`. Phase 1 is read-only (returns the edits);
- * the dispatcher composes + applies in a future ticket.
- */
-export async function symbolsFormatTool(ctx, lang, file, options) {
-    const toolCallId = recordToolCall(ctx.session, 'symbols_format', `${lang}:${file}`);
-    return guard(ctx, 'symbols_format', toolCallId, async () => {
-        const client = ctx.lspClients?.get(lang);
-        if (!client)
-            return unavailable(lang);
-        const result = await formatFile(transportFromLspClient(client), file, options);
-        return { ok: true, value: result };
-    });
-}
-/**
- * PUGI-78 Phase 1: symbols.diagnostics.
- *
- * Pulls the cached `publishDiagnostics` payload for the file. Mirrors
- * the legacy `lspDiagnostics` tool but exposed via the namespaced
- * `symbols.*` surface for discoverability.
- */
-export async function symbolsDiagnosticsTool(ctx, lang, file) {
-    const toolCallId = recordToolCall(ctx.session, 'symbols_diagnostics', `${lang}:${file}`);
-    return guard(ctx, 'symbols_diagnostics', toolCallId, async () => {
-        const client = ctx.lspClients?.get(lang);
-        if (!client)
-            return unavailable(lang);
-        const result = await diagnosticsFor(transportFromLspClient(client), file);
-        const capped = capDiagnostics(result);
-        return { ok: true, value: capped.value, ...(capped.truncated ? { truncated: true } : {}) };
-    });
-}
-function workspaceForCache(ctx) {
-    // ToolContext exposes `root` (the workspace root). Fall back to a
-    // tagged anonymous workspace when somehow absent so the cache still
-    // keys deterministically.
-    const root = ctx.root;
-    if (typeof root === 'string' && root.length > 0)
-        return root;
-    return '<unknown>';
-}
-function getSymbolCacheFromCtx(ctx) {
-    // The agent dispatcher injects an optional cache via the ctx — when
-    // present we use the dispatcher-scoped cache so test harnesses can
-    // inject a deterministic clock. When absent, we fall back to the
-    // process-global cache.
-    if (ctx.symbolCache)
-        return ctx.symbolCache;
-    return getGlobalSymbolCache();
-}
-function notFound(verb) {
-    return {
-        ok: false,
-        reason: 'lsp_not_found',
-        detail: `LSP returned no ${verb} for the requested position.`,
-    };
-}
-function capSymbolReferences(items) {
-    const COUNT_CAP = 200;
-    if (items.length === 0)
-        return { value: items, truncated: false };
-    const trimmed = items.slice(0, COUNT_CAP);
-    const serialized = JSON.stringify(trimmed);
-    if (Buffer.byteLength(serialized, 'utf8') <= LSP_PAYLOAD_CAP_BYTES && trimmed.length === items.length) {
-        return { value: trimmed, truncated: false };
-    }
-    let upper = trimmed.length;
-    while (upper > 1) {
-        const half = Math.floor(upper / 2);
-        const sub = trimmed.slice(0, half);
-        if (Buffer.byteLength(JSON.stringify(sub), 'utf8') <= LSP_PAYLOAD_CAP_BYTES) {
-            return { value: sub, truncated: true };
-        }
-        upper = half;
-    }
-    return { value: trimmed.slice(0, 1), truncated: true };
-}
-/** Test-only surface so specs can poke truncation directly. */
-export const __test__ = {
-    truncate,
-    capLocations,
-    capDiagnostics,
-    capSymbolReferences,
-    LSP_PAYLOAD_CAP_BYTES,
-};
-//# sourceMappingURL=lsp-tools.js.map