@pugi/cli 0.1.0-beta.8 → 0.1.0-beta.87

package/dist/core/lsp/language-detect.js

@@ -0,0 +1,66 @@
+/**
+ * Language-from-extension detection — .
+ *
+ * Single source of truth for "given a file path, which `LspLanguage`
+ * slug do we route to". The `runtime/commands/lsp.ts` shipped its
+ * own inline `inferLanguage` switch; L15 (post-edit auto-diagnostics)
+ * needs the same lookup from `core/engine/tool-bridge.ts`, so we lift
+ * the table into a dedicated module to avoid a second copy drifting
+ * out of sync.
+ *
+ * Returning `undefined` is the calling code's signal to silently skip
+ * LSP — an unsupported extension is NOT an error, it just means "no
+ * diagnostics for this file". The tool-bridge hook treats this as a
+ * no-op envelope tail.
+ *
+ * Adding a new language requires THREE coordinated changes:
+ *  1. Add the `LspLanguage` slug + server descriptor in `client.ts`.
+ *  2. Map its extensions here.
+ *  3. Add a `lsp-language-matrix` spec row exercising the new ext.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { extname } from 'node:path';
+/**
+ * Lower-case extension (including the dot) → LSP language slug.
+ * Mirror of the switch in `runtime/commands/lsp.ts::inferLanguage`.
+ * The table form lets tests assert coverage and lets new languages
+ * land with one edit instead of two.
+ */
+export const EXTENSION_TO_LANGUAGE = {
+    '.ts': 'ts',
+    '.tsx': 'ts',
+    '.mts': 'ts',
+    '.cts': 'ts',
+    '.js': 'js',
+    '.jsx': 'js',
+    '.mjs': 'js',
+    '.cjs': 'js',
+    '.py': 'py',
+    '.pyi': 'py',
+    '.go': 'go',
+    '.rs': 'rust',
+};
+/**
+ * Infer the `LspLanguage` for a workspace-relative or absolute path.
+ * Returns `undefined` for unmapped extensions — the caller decides
+ * whether that is silently skipped (post-edit hook) or surfaced as
+ * `language_unsupported` (`pugi lsp` CLI).
+ */
+export function languageForFile(file) {
+    const ext = extname(file).toLowerCase();
+    if (!ext)
+        return undefined;
+    return EXTENSION_TO_LANGUAGE[ext];
+}
+/**
+ * Return every extension currently mapped to the given language.
+ * Used by the matrix spec to assert coverage without re-typing the
+ * extension list.
+ */
+export function extensionsForLanguage(lang) {
+    return Object.entries(EXTENSION_TO_LANGUAGE)
+        .filter(([, value]) => value === lang)
+        .map(([ext]) => ext);
+}
+//# sourceMappingURL=language-detect.js.map

package/dist/core/lsp/post-edit-diagnostics.js

@@ -0,0 +1,171 @@
+/**
+ * Post-edit diagnostics — .
+ *
+ * the upstream tool's leak intel surfaced this pattern: after a `FileEdit` /
+ * `Write` tool call lands, an LSP diagnostic pass runs on the touched
+ * file and the result is appended to the tool envelope before the
+ * model sees it. The model then self-corrects in the same turn —
+ * "TS2304: Cannot find name 'undef'" comes back, the model fixes the
+ * typo in the next tool call, no operator round-trip needed.
+ *
+ * This module is the Pugi side of that pattern:
+ *
+ *  1. The tool-bridge calls `runPostEditDiagnostics(path, ctx)` after
+ *     a successful `edit` / `write` / `multi_edit`.
+ *  2. We infer the language from the extension (`language-detect`).
+ *     Unsupported extension → `{ skip: true }` and the bridge appends
+ *     nothing.
+ *  3. We borrow (or lazily start) the per-language cached client
+ *     from `cache.ts`. A spawn failure → `{ skip: true }` and the
+ *     envelope stays clean. Silence on failure is intentional: an
+ *     operator who has not installed `typescript-language-server`
+ *     should not see an LSP nag on every edit.
+ *  4. We pull diagnostics with a hard 5s ceiling. A timeout logs a
+ *     warning on stderr (gated on `PUGI_LSP_DEBUG=1`) and skips —
+ *     the envelope is never blocked on LSP.
+ *  5. We format the surviving diagnostics into a readable tail
+ *     mirroring the leak format:
+ *
+ *        LSP DIAGNOSTICS (typescript):
+ *          foo.ts:42:5 error TS2304: Cannot find name 'undef'.
+ *          foo.ts:51:1 warn TS6133: 'unused' is declared.
+ *
+ * The bridge concatenates this tail onto its existing `wrote ...` /
+ * `edited ...` body with a single newline separator. When there are
+ * zero diagnostics we return `{ skip: true }` so the existing body
+ * is unchanged — the "no news is good news" path stays terse.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { isAbsolute, relative, resolve } from 'node:path';
+import { getOrStartLspClient } from './cache.js';
+import { languageForFile } from './language-detect.js';
+const DEFAULT_TIMEOUT_MS = 5_000;
+/**
+ * Hard cap on how many diagnostics we surface to the model. A file
+ * with 200 errors after a broken bulk edit would otherwise blow the
+ * context window; the model can re-run `pugi lsp diagnostics` if
+ * it needs the full list.
+ */
+const MAX_DIAGNOSTICS = 25;
+export async function runPostEditDiagnostics(filePath, opts) {
+    const lang = languageForFile(filePath);
+    if (!lang) {
+        return { skip: true, reason: 'unsupported_language' };
+    }
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const clientResult = await loadClient(lang, opts);
+    if (!clientResult.ok) {
+        return { skip: true, reason: mapStartFailure(clientResult.reason) };
+    }
+    // Run diagnostics with a hard timeout. The underlying LspClient has
+    // its own per-request timeout (5s default) but a slow handshake
+    // can blow past it; we belt-and-suspenders here so the agent loop
+    // never blocks on LSP.
+    const relPath = toWorkspaceRelative(filePath, opts.cwd);
+    const diagnosticsPromise = clientResult.client.diagnostics(relPath);
+    let timer;
+    const timeoutPromise = new Promise((resolveFn) => {
+        timer = setTimeout(() => resolveFn({ timedOut: true }), timeoutMs);
+        timer.unref();
+    });
+    const race = await Promise.race([
+        diagnosticsPromise.then((value) => ({ timedOut: false, value })),
+        timeoutPromise,
+    ]);
+    if (timer)
+        clearTimeout(timer);
+    if (race.timedOut) {
+        const writeFn = opts.debugWrite ?? ((line) => {
+            if (process.env.PUGI_LSP_DEBUG === '1')
+                process.stderr.write(`${line}\n`);
+        });
+        writeFn(`[pugi-lsp] post-edit diagnostics for ${relPath} timed out after ${timeoutMs}ms (lang=${lang})`);
+        return { skip: true, reason: 'timeout' };
+    }
+    const diag = race.value;
+    if (!diag.ok) {
+        return { skip: true, reason: 'lsp_error' };
+    }
+    if (diag.value.length === 0) {
+        return { skip: true, reason: 'no_diagnostics' };
+    }
+    const tail = formatDiagnosticsTail(relPath, lang, diag.value);
+    return { skip: false, tail, count: diag.value.length, language: lang };
+}
+async function loadClient(lang, opts) {
+    if (opts.clientLoader) {
+        return opts.clientLoader(lang);
+    }
+    const { cwd, timeoutMs, clientLoader: _ignoredA, debugWrite: _ignoredB, ...rest } = opts;
+    const result = await getOrStartLspClient(lang, { cwd, ...rest });
+    if (!result.ok) {
+        return { ok: false, reason: result.reason, detail: result.detail };
+    }
+    return { ok: true, client: result.client };
+}
+function mapStartFailure(reason) {
+    if (reason === 'lsp_unavailable' || reason === 'language_unsupported')
+        return 'lsp_unavailable';
+    if (reason === 'lsp_disabled')
+        return 'lsp_disabled';
+    return 'lsp_error';
+}
+/**
+ * Convert an absolute or workspace-relative path into the form the
+ * LSP client expects — same shape as `runtime/commands/lsp.ts` uses.
+ */
+function toWorkspaceRelative(filePath, cwd) {
+    if (!isAbsolute(filePath))
+        return filePath;
+    const rel = relative(cwd, resolve(cwd, filePath));
+    return rel || filePath;
+}
+/**
+ * Format diagnostics into the leak-shaped envelope tail. Pure function
+ * exported for unit tests to assert the line format independent of
+ * any LSP plumbing.
+ */
+export function formatDiagnosticsTail(relPath, lang, diagnostics) {
+    const visible = diagnostics.slice(0, MAX_DIAGNOSTICS);
+    const truncated = diagnostics.length > visible.length;
+    const lines = [`LSP DIAGNOSTICS (${LANGUAGE_LABELS[lang]}):`];
+    for (const diag of visible) {
+        const line = diag.range.start.line + 1; // LSP is zero-based; humans expect 1-based.
+        const col = diag.range.start.character + 1;
+        const severity = SEVERITY_LABELS[diag.severityLabel];
+        const code = diag.code !== undefined && diag.code !== '' ? ` ${diag.code}` : '';
+        const source = diag.source ? `${diag.source}` : '';
+        const head = source ? `${severity}${code} (${source}):` : `${severity}${code}:`;
+        lines.push(` ${relPath}:${line}:${col} ${head} ${diag.message}`);
+    }
+    if (truncated) {
+        lines.push(` ... ${diagnostics.length - visible.length} more diagnostic(s) — re-run pugi lsp diagnostics ${relPath} for the full list`);
+    }
+    return lines.join('\n');
+}
+const LANGUAGE_LABELS = {
+    ts: 'typescript',
+    js: 'javascript',
+    py: 'python',
+    go: 'go',
+    rust: 'rust',
+};
+/**
+ * Map LSP severity label → the short token the leak envelope uses.
+ * "warn" is shorter than "warning" and matches the upstream tool's leak
+ * verbatim; the rest mirror LSP terminology.
+ */
+const SEVERITY_LABELS = {
+    error: 'error',
+    warning: 'warn ',
+    info: 'info ',
+    hint: 'hint ',
+};
+/** Test-only surface so specs can poke the pure helpers without LSP. */
+export const __test__ = {
+    formatDiagnosticsTail,
+    MAX_DIAGNOSTICS,
+    DEFAULT_TIMEOUT_MS,
+};
+//# sourceMappingURL=post-edit-diagnostics.js.map

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

@@ -0,0 +1,372 @@
+/**
+ * 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`. Production
+ * wire-up. `documentSymbols` / `workspaceSymbols` are omitted on
+ * purpose — the `LspClient` does not expose them, so the Phase 1
+ * surface degrades to `[]`. Phase 2 follows.
+ */
+export function transportFromLspClient(client) {
+    return {
+        definition: (file, pos) => client.definition(file, pos),
+        references: (file, pos) => client.references(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;
+}
+// -- 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,
+};
+//# sourceMappingURL=symbol-tools.js.map