@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.90

package/dist/core/lsp/symbol-tools.js

@@ -0,0 +1,664 @@
+/**
+ * LSP `SymbolKind` enum — mirrors the official numbering from the LSP
+ * spec §3.17.7. We re-export the integers (not the names) because the
+ * Aider repomap stores numeric kinds verbatim. Callers that want a
+ * human label use `symbolKindLabel`.
+ */
+export const SYMBOL_KIND = {
+    File: 1,
+    Module: 2,
+    Namespace: 3,
+    Package: 4,
+    Class: 5,
+    Method: 6,
+    Property: 7,
+    Field: 8,
+    Constructor: 9,
+    Enum: 10,
+    Interface: 11,
+    Function: 12,
+    Variable: 13,
+    Constant: 14,
+    String: 15,
+    Number: 16,
+    Boolean: 17,
+    Array: 18,
+    Object: 19,
+    Key: 20,
+    Null: 21,
+    EnumMember: 22,
+    Struct: 23,
+    Event: 24,
+    Operator: 25,
+    TypeParameter: 26,
+};
+const SYMBOL_KIND_LABELS = {
+    1: 'file',
+    2: 'module',
+    3: 'namespace',
+    4: 'package',
+    5: 'class',
+    6: 'method',
+    7: 'property',
+    8: 'field',
+    9: 'constructor',
+    10: 'enum',
+    11: 'interface',
+    12: 'function',
+    13: 'variable',
+    14: 'constant',
+    15: 'string',
+    16: 'number',
+    17: 'boolean',
+    18: 'array',
+    19: 'object',
+    20: 'key',
+    21: 'null',
+    22: 'enum-member',
+    23: 'struct',
+    24: 'event',
+    25: 'operator',
+    26: 'type-parameter',
+};
+/** Human-readable kind label (`'function'`, `'class'`, ...) for printing. */
+export function symbolKindLabel(kind) {
+    if (typeof kind !== 'number')
+        return 'unknown';
+    return SYMBOL_KIND_LABELS[kind] ?? 'unknown';
+}
+/**
+ * Build a `SymbolToolsTransport` from a real `LspClient`. PUGI-78 Phase
+ * 1: wires every method the client exposes (13 total). Methods the
+ * `LspClient` does NOT support yet stay omitted on the returned
+ * transport so the symbol-tools surface degrades to null / [] without
+ * forcing the caller to wrap.
+ */
+export function transportFromLspClient(client) {
+    return {
+        definition: (file, pos) => client.definition(file, pos),
+        references: (file, pos) => client.references(file, pos),
+        documentSymbols: (file) => client.documentSymbols(file),
+        workspaceSymbols: (query) => client.workspaceSymbols(query),
+        hover: (file, pos) => client.hover(file, pos),
+        signatureHelp: (file, pos) => client.signatureHelp(file, pos),
+        implementations: (file, pos) => client.implementations(file, pos),
+        typeDefinition: (file, pos) => client.typeDefinition(file, pos),
+        rename: (file, pos, newName) => client.rename(file, pos, newName),
+        prepareRename: (file, pos) => client.prepareRename(file, pos),
+        codeActions: (file, range) => client.codeActions(file, range),
+        formatting: (file, options) => client.formatting(file, undefined, options),
+        diagnostics: (file) => client.diagnostics(file),
+        callHierarchy: (file, pos) => client.callHierarchy(file, pos),
+    };
+}
+/**
+ * Resolve the first definition for the symbol at `(line, character)`
+ * in `filePath`. Returns `null` when:
+ *
+ *  - `filePath` is empty / whitespace
+ *  - the transport's `definition` call returns `ok: false`
+ *  - the server reports an empty array
+ *  - the transport itself throws (caught — never re-raised)
+ *
+ * Multi-hit definitions (TS overloads, polymorphic methods) collapse
+ * to the first location; the engine can call `findReferences` to fan
+ * out from there. Matches Aider's `repomap.find_definition` shape.
+ */
+export async function findDefinition(transport, filePath, line, character) {
+    if (!isNonEmptyString(filePath))
+        return null;
+    if (!isFiniteNonNegativeInt(line) || !isFiniteNonNegativeInt(character)) {
+        return null;
+    }
+    let result;
+    try {
+        result = await transport.definition(filePath, { line, character });
+    }
+    catch {
+        return null;
+    }
+    if (!result.ok)
+        return null;
+    const first = result.value[0];
+    if (!first)
+        return null;
+    const file = pickFilePath(first);
+    if (!isNonEmptyString(file))
+        return null;
+    return {
+        file,
+        line: first.range.start.line,
+        character: first.range.start.character,
+    };
+}
+/**
+ * List every reference (including the declaration) for the symbol at
+ * `(line, character)` in `filePath`. Returns `[]` on any failure mode
+ * matching `findDefinition` plus the empty-array server response.
+ */
+export async function findReferences(transport, filePath, line, character) {
+    if (!isNonEmptyString(filePath))
+        return [];
+    if (!isFiniteNonNegativeInt(line) || !isFiniteNonNegativeInt(character)) {
+        return [];
+    }
+    let result;
+    try {
+        result = await transport.references(filePath, { line, character });
+    }
+    catch {
+        return [];
+    }
+    if (!result.ok)
+        return [];
+    const out = [];
+    for (const loc of result.value) {
+        const file = pickFilePath(loc);
+        if (!isNonEmptyString(file))
+            continue;
+        out.push({
+            file,
+            line: loc.range.start.line,
+            character: loc.range.start.character,
+        });
+    }
+    return out;
+}
+/**
+ * Outline the symbols defined in `filePath`. Returns `[]` when:
+ *
+ *  - `filePath` is empty
+ *  - the transport does not implement `documentSymbols` (Phase 1
+ *    default — the `LspClient` lacks the wire call)
+ *  - the transport's `documentSymbols` call returns `ok: false`
+ *  - the server returns an empty / malformed list
+ *  - the transport throws
+ *
+ * Handles BOTH LSP response shapes: hierarchical `DocumentSymbol[]`
+ * (with `selectionRange` + `children`) and flat `SymbolInformation[]`
+ * (with `location.range`). Children are flattened into the same array
+ * so the engine sees one row per symbol regardless of nesting; the
+ * `containerName` field records the parent's name for hierarchy.
+ */
+export async function listDocumentSymbols(transport, filePath) {
+    if (!isNonEmptyString(filePath))
+        return [];
+    if (!transport.documentSymbols)
+        return [];
+    let result;
+    try {
+        result = await transport.documentSymbols(filePath);
+    }
+    catch {
+        return [];
+    }
+    if (!result.ok)
+        return [];
+    const out = [];
+    for (const raw of result.value) {
+        walkDocumentSymbol(raw, undefined, out);
+    }
+    return out;
+}
+/**
+ * Workspace-wide symbol fuzzy search. Returns `[]` when:
+ *
+ *  - `query` is empty / whitespace
+ *  - the transport does not implement `workspaceSymbols`
+ *  - the transport's call returns `ok: false`
+ *  - the server returns an empty / malformed list
+ *  - the transport throws
+ *
+ * Per LSP §3.17.13, the server is free to define its own matching
+ * algorithm (substring / fuzzy / prefix). We do not re-rank — the
+ * server's ranking is authoritative.
+ */
+export async function findWorkspaceSymbol(transport, query) {
+    if (!isNonEmptyString(query))
+        return [];
+    if (!transport.workspaceSymbols)
+        return [];
+    let result;
+    try {
+        result = await transport.workspaceSymbols(query);
+    }
+    catch {
+        return [];
+    }
+    if (!result.ok)
+        return [];
+    const out = [];
+    for (const raw of result.value) {
+        const parsed = parseWorkspaceSymbol(raw);
+        if (parsed)
+            out.push(parsed);
+    }
+    return out;
+}
+/**
+ * PUGI-78 Phase 1: hover (type info + docstring). Returns null when:
+ *
+ *  - `filePath` is empty / whitespace
+ *  - `line` / `character` non-finite or negative
+ *  - the transport does not implement `hover`
+ *  - `ok: false` from the transport
+ *  - the server reports no hover (cursor not on a symbol)
+ *  - the transport throws
+ *
+ * Caps the body at 4 KB so a verbose generic type signature does not
+ * blow the agent's context window. The cap mirrors the `lspHover`
+ * tool's 8 KB cap halved — the symbol surface is closer to "give me
+ * one sentence" than the full hover blob.
+ */
+export async function hoverSymbol(transport, filePath, line, character) {
+    if (!isNonEmptyString(filePath))
+        return null;
+    if (!isFiniteNonNegativeInt(line) || !isFiniteNonNegativeInt(character))
+        return null;
+    if (!transport.hover)
+        return null;
+    let result;
+    try {
+        result = await transport.hover(filePath, { line, character });
+    }
+    catch {
+        return null;
+    }
+    if (!result.ok)
+        return null;
+    if (!result.value)
+        return null;
+    const HOVER_CAP_BYTES = 4 * 1024;
+    const raw = result.value.content;
+    const bytes = Buffer.byteLength(raw, 'utf8');
+    const truncated = bytes > HOVER_CAP_BYTES;
+    const content = truncated
+        ? Buffer.from(raw, 'utf8').subarray(0, HOVER_CAP_BYTES).toString('utf8') + '\n... [truncated]'
+        : raw;
+    return {
+        content,
+        ...(result.value.range ? { range: result.value.range } : {}),
+        ...(truncated ? { truncated: true } : {}),
+    };
+}
+/**
+ * PUGI-78 Phase 1: function signature at a call site. Returns null when
+ * the transport does not implement `signatureHelp` OR the server
+ * reports no signature OR the transport fails / throws.
+ */
+export async function signatureAt(transport, filePath, line, character) {
+    if (!isNonEmptyString(filePath))
+        return null;
+    if (!isFiniteNonNegativeInt(line) || !isFiniteNonNegativeInt(character))
+        return null;
+    if (!transport.signatureHelp)
+        return null;
+    let result;
+    try {
+        result = await transport.signatureHelp(filePath, { line, character });
+    }
+    catch {
+        return null;
+    }
+    if (!result.ok)
+        return null;
+    if (!result.value)
+        return null;
+    const out = { label: result.value.label, parameters: result.value.parameters };
+    if (result.value.documentation)
+        out.documentation = result.value.documentation;
+    if (typeof result.value.activeParameter === 'number')
+        out.activeParameter = result.value.activeParameter;
+    return out;
+}
+/**
+ * PUGI-78 Phase 1: implementations of an interface / abstract method.
+ * Returns `[]` on any failure mode (parity with `findReferences`).
+ */
+export async function findImplementations(transport, filePath, line, character) {
+    if (!isNonEmptyString(filePath))
+        return [];
+    if (!isFiniteNonNegativeInt(line) || !isFiniteNonNegativeInt(character))
+        return [];
+    if (!transport.implementations)
+        return [];
+    let result;
+    try {
+        result = await transport.implementations(filePath, { line, character });
+    }
+    catch {
+        return [];
+    }
+    if (!result.ok)
+        return [];
+    return collapseLocations(result.value);
+}
+/**
+ * PUGI-78 Phase 1: type-definition (vs value-definition). Returns null
+ * matching `findDefinition`'s contract.
+ */
+export async function findTypeDefinition(transport, filePath, line, character) {
+    if (!isNonEmptyString(filePath))
+        return null;
+    if (!isFiniteNonNegativeInt(line) || !isFiniteNonNegativeInt(character))
+        return null;
+    if (!transport.typeDefinition)
+        return null;
+    let result;
+    try {
+        result = await transport.typeDefinition(filePath, { line, character });
+    }
+    catch {
+        return null;
+    }
+    if (!result.ok)
+        return null;
+    const first = result.value[0];
+    if (!first)
+        return null;
+    const file = pickFilePath(first);
+    if (!isNonEmptyString(file))
+        return null;
+    return { file, line: first.range.start.line, character: first.range.start.character };
+}
+export async function renameSymbol(transport, filePath, line, character, newName) {
+    if (!isNonEmptyString(filePath))
+        return null;
+    if (!isFiniteNonNegativeInt(line) || !isFiniteNonNegativeInt(character))
+        return null;
+    if (!isNonEmptyString(newName))
+        return null;
+    if (!transport.rename)
+        return null;
+    // Best-effort prepare-rename precheck. If the server says the cursor
+    // is not on a renameable token, we return null without dispatching
+    // the full rename — saves a wasted round-trip + avoids returning a
+    // misleading "0 edits" preview.
+    if (transport.prepareRename) {
+        try {
+            const prep = await transport.prepareRename(filePath, { line, character });
+            if (prep.ok && prep.value === null)
+                return null;
+        }
+        catch {
+            // Continue — some servers fail prepare-rename but still execute
+            // the full rename. Phase 1 honors the looser fallback.
+        }
+    }
+    let result;
+    try {
+        result = await transport.rename(filePath, { line, character }, newName);
+    }
+    catch {
+        return null;
+    }
+    if (!result.ok)
+        return null;
+    if (!result.value)
+        return null;
+    if (result.value.edits.length === 0)
+        return null;
+    return { files: result.value.files, edits: result.value.edits };
+}
+/**
+ * PUGI-78 Phase 1: code-action / quick-fix list at a range. Returns
+ * `[]` on any failure mode.
+ */
+export async function codeActionsAt(transport, filePath, startLine, startChar, endLine, endChar) {
+    if (!isNonEmptyString(filePath))
+        return [];
+    if (!isFiniteNonNegativeInt(startLine) ||
+        !isFiniteNonNegativeInt(startChar) ||
+        !isFiniteNonNegativeInt(endLine) ||
+        !isFiniteNonNegativeInt(endChar)) {
+        return [];
+    }
+    if (!transport.codeActions)
+        return [];
+    const range = {
+        start: { line: startLine, character: startChar },
+        end: { line: endLine, character: endChar },
+    };
+    let result;
+    try {
+        result = await transport.codeActions(filePath, range);
+    }
+    catch {
+        return [];
+    }
+    if (!result.ok)
+        return [];
+    return [...result.value];
+}
+/**
+ * PUGI-78 Phase 1: formatter — returns the text edits the server would
+ * apply. Returns `[]` on any failure mode.
+ */
+export async function formatFile(transport, filePath, options) {
+    if (!isNonEmptyString(filePath))
+        return [];
+    if (!transport.formatting)
+        return [];
+    let result;
+    try {
+        result = await transport.formatting(filePath, options);
+    }
+    catch {
+        return [];
+    }
+    if (!result.ok)
+        return [];
+    return [...result.value];
+}
+/**
+ * PUGI-78 Phase 1: diagnostics for `filePath`. Returns `[]` on any
+ * failure mode. Mirrors the agent surface of `lspDiagnostics` but
+ * folded into the symbols.* namespace for ergonomic discoverability.
+ */
+export async function diagnosticsFor(transport, filePath) {
+    if (!isNonEmptyString(filePath))
+        return [];
+    if (!transport.diagnostics)
+        return [];
+    let result;
+    try {
+        result = await transport.diagnostics(filePath);
+    }
+    catch {
+        return [];
+    }
+    if (!result.ok)
+        return [];
+    return [...result.value];
+}
+/**
+ * PUGI-78 Phase 1: call hierarchy at a symbol position. Returns the
+ * incoming and outgoing edges. Empty arrays on any failure mode.
+ */
+export async function callHierarchyAt(transport, filePath, line, character) {
+    const empty = { incoming: [], outgoing: [] };
+    if (!isNonEmptyString(filePath))
+        return empty;
+    if (!isFiniteNonNegativeInt(line) || !isFiniteNonNegativeInt(character))
+        return empty;
+    if (!transport.callHierarchy)
+        return empty;
+    let result;
+    try {
+        result = await transport.callHierarchy(filePath, { line, character });
+    }
+    catch {
+        return empty;
+    }
+    if (!result.ok)
+        return empty;
+    return { incoming: [...result.value.incoming], outgoing: [...result.value.outgoing] };
+}
+/**
+ * Internal: collapse `LspLocation[]` to flat references the agent
+ * surface ships. Identical to the `findReferences` loop body — lifted
+ * to avoid a second copy.
+ */
+function collapseLocations(locations) {
+    const out = [];
+    for (const loc of locations) {
+        const file = pickFilePath(loc);
+        if (!isNonEmptyString(file))
+            continue;
+        out.push({
+            file,
+            line: loc.range.start.line,
+            character: loc.range.start.character,
+        });
+    }
+    return out;
+}
+// -- internals ---------------------------------------------------------------
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isFiniteNonNegativeInt(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+/**
+ * Prefer the workspace-relative `path` from `client.ts::normalizeLocations`;
+ * fall back to the raw URI when the server reports an out-of-workspace
+ * location. Either form is a valid identifier for the caller — the
+ * engine prefers relative paths for prompts but URIs are still useful
+ * for tracing.
+ */
+function pickFilePath(loc) {
+    if (isNonEmptyString(loc.path))
+        return loc.path;
+    if (isNonEmptyString(loc.uri))
+        return loc.uri;
+    return '';
+}
+/**
+ * Recursive walk over a (possibly hierarchical) `DocumentSymbol`.
+ * Emits one `DocumentSymbol` row per node — children inherit the
+ * parent's `name` as their `containerName`. Tolerates both
+ * `SymbolInformation` (flat, has `location.range`) and the modern
+ * hierarchical shape (`selectionRange` + `children`).
+ */
+function walkDocumentSymbol(raw, parentName, out) {
+    if (!raw || typeof raw !== 'object')
+        return;
+    const name = typeof raw.name === 'string' ? raw.name : '';
+    const kind = typeof raw.kind === 'number' ? raw.kind : 0;
+    if (!name || !kind)
+        return;
+    const pos = pickDocumentSymbolPosition(raw);
+    if (!pos)
+        return;
+    const containerName = typeof raw.containerName === 'string' && raw.containerName.length > 0
+        ? raw.containerName
+        : parentName;
+    out.push({
+        name,
+        kind,
+        line: pos.line,
+        character: pos.character,
+        ...(containerName ? { containerName } : {}),
+    });
+    if (Array.isArray(raw.children)) {
+        for (const child of raw.children) {
+            walkDocumentSymbol(child, name, out);
+        }
+    }
+}
+/**
+ * LSP `DocumentSymbol` (hierarchical) carries `selectionRange.start`,
+ * the precise character position of the symbol name. The legacy
+ * `SymbolInformation` shape carries `location.range.start` instead.
+ * Tolerate both; prefer `selectionRange` when present (more precise).
+ */
+function pickDocumentSymbolPosition(raw) {
+    const sel = pickRangeStart(raw.selectionRange);
+    if (sel)
+        return sel;
+    const range = pickRangeStart(raw.range);
+    if (range)
+        return range;
+    if (raw.location && typeof raw.location === 'object') {
+        const locRange = pickRangeStart(raw.location.range);
+        if (locRange)
+            return locRange;
+    }
+    return null;
+}
+function pickRangeStart(rawRange) {
+    if (!rawRange || typeof rawRange !== 'object')
+        return null;
+    const start = rawRange.start;
+    if (!start || typeof start !== 'object')
+        return null;
+    const line = start.line;
+    const character = start.character;
+    if (typeof line !== 'number' || typeof character !== 'number')
+        return null;
+    if (!Number.isFinite(line) || !Number.isFinite(character))
+        return null;
+    if (line < 0 || character < 0)
+        return null;
+    return { line, character };
+}
+function parseWorkspaceSymbol(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const name = typeof raw.name === 'string' ? raw.name : '';
+    const kind = typeof raw.kind === 'number' ? raw.kind : 0;
+    if (!name || !kind)
+        return null;
+    const location = raw.location;
+    if (!location || typeof location !== 'object')
+        return null;
+    const file = pickWorkspaceSymbolFile(location);
+    if (!file)
+        return null;
+    const pos = pickRangeStart(location.range);
+    if (!pos)
+        return null;
+    const containerName = typeof raw.containerName === 'string' && raw.containerName.length > 0
+        ? raw.containerName
+        : undefined;
+    return {
+        name,
+        file,
+        line: pos.line,
+        kind,
+        ...(containerName ? { containerName } : {}),
+    };
+}
+/**
+ * Workspace-symbol locations land as either a full `Location`
+ * (`{ uri, range }`) or LSP 3.17's `LocationLink` shape
+ * (`{ targetUri, targetRange, ... }`). Either form is acceptable;
+ * we surface the URI string verbatim and let the engine layer
+ * convert to a workspace-relative path when needed (mirrors how
+ * `client.ts::normalizeLocations` handles definition results).
+ */
+function pickWorkspaceSymbolFile(location) {
+    const uri = location['uri'];
+    if (typeof uri === 'string' && uri.length > 0)
+        return uri;
+    const targetUri = location['targetUri'];
+    if (typeof targetUri === 'string' && targetUri.length > 0)
+        return targetUri;
+    return '';
+}
+/**
+ * Test-only surface — re-exports internals for direct assertion of
+ * parsing rules without running every primitive end-to-end. Keeping
+ * the seam typed (instead of using `@ts-ignore` in the spec) preserves
+ * `noImplicitAny` compliance project-wide.
+ */
+export const __test__ = {
+    parseWorkspaceSymbol,
+    pickDocumentSymbolPosition,
+    pickRangeStart,
+    symbolKindLabel,
+    walkDocumentSymbol,
+    collapseLocations,
+};
+//# sourceMappingURL=symbol-tools.js.map