weavatrix 0.2.13 → 0.2.14

package/src/precision/lsp-client/protocol.js

@@ -0,0 +1,212 @@
+import {JSON_RPC_VERSION, positiveInteger} from './constants.js'
+import {LspProtocolError, LspTimeoutError} from './errors.js'
+import {WEAVATRIX_VERSION} from '../../version.js'
+
+export function assertPosition(position) {
+    if (position == null || typeof position !== 'object') throw new TypeError('position is required')
+    const line = Number(position.line)
+    const character = Number(position.character)
+    if (!Number.isSafeInteger(line) || line < 0 || !Number.isSafeInteger(character) || character < 0) {
+        throw new TypeError('position line and character must be non-negative integers')
+    }
+    return {line, character}
+}
+
+function normalizeRange(range) {
+    if (range == null || typeof range !== 'object') throw new LspProtocolError('LSP location is missing a range')
+    return {start: assertPosition(range.start), end: assertPosition(range.end)}
+}
+
+function jsonRpcError(error) {
+    const wrapped = new Error(error?.message || 'LSP request failed')
+    wrapped.name = 'LspResponseError'
+    wrapped.code = error?.code
+    wrapped.data = error?.data
+    return wrapped
+}
+
+export function assertClientWritable(client) {
+    if (!['running', 'initialized', 'stopping'].includes(client.state) || client.child.stdin?.destroyed) {
+        throw new Error(`LSP client is not writable (state=${client.state})`)
+    }
+}
+
+export function writeClientMessage(client, message) {
+    assertClientWritable(client)
+    const body = Buffer.from(JSON.stringify(message), 'utf8')
+    if (body.length > client.maxMessageBytes) {
+        throw new LspProtocolError(`Outgoing LSP message exceeds ${client.maxMessageBytes} byte limit`)
+    }
+    const header = Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'ascii')
+    return new Promise((resolveWrite, rejectWrite) => {
+        client.child.stdin.write(
+            Buffer.concat([header, body]),
+            (error) => error ? rejectWrite(error) : resolveWrite(),
+        )
+    })
+}
+
+export async function requestFromClient(client, method, params = null, {timeoutMs = client.requestTimeoutMs} = {}) {
+    if (typeof method !== 'string' || method === '') throw new TypeError('LSP method is required')
+    const boundedTimeout = positiveInteger(timeoutMs, client.requestTimeoutMs, 'timeoutMs')
+    const id = client.nextId++
+    let entry
+    const response = new Promise((resolveResponse, rejectResponse) => {
+        const timer = setTimeout(() => {
+            if (client.pending.get(id) !== entry) return
+            client.pending.delete(id)
+            void writeClientMessage(client, {
+                jsonrpc: JSON_RPC_VERSION,
+                method: '$/cancelRequest',
+                params: {id},
+            }).catch(() => {})
+            rejectResponse(new LspTimeoutError(method, boundedTimeout))
+        }, boundedTimeout)
+        entry = {method, timer, resolve: resolveResponse, reject: rejectResponse}
+        client.pending.set(id, entry)
+    })
+    try {
+        await writeClientMessage(client, {jsonrpc: JSON_RPC_VERSION, id, method, params})
+    } catch (error) {
+        if (client.pending.get(id) === entry) {
+            clearTimeout(entry.timer)
+            client.pending.delete(id)
+            entry.reject(error)
+        }
+    }
+    return response
+}
+
+export async function notifyClient(client, method, params = null) {
+    if (typeof method !== 'string' || method === '') throw new TypeError('LSP method is required')
+    await writeClientMessage(client, {jsonrpc: JSON_RPC_VERSION, method, params})
+}
+
+export async function initializeClient(client, {
+    capabilities = {},
+    initializationOptions,
+    clientInfo = {name: 'weavatrix', version: WEAVATRIX_VERSION},
+} = {}) {
+    if (client.state !== 'running') throw new Error(`LSP initialize is invalid in state=${client.state}`)
+    const workspaceName = client.normalizer.rootPath.split(/[\\/]/).pop() || 'repository'
+    const result = await requestFromClient(client, 'initialize', {
+        processId: process.pid,
+        clientInfo,
+        rootUri: client.normalizer.rootUri,
+        capabilities,
+        initializationOptions,
+        workspaceFolders: [{uri: client.normalizer.rootUri, name: workspaceName}],
+    })
+    await notifyClient(client, 'initialized', {})
+    client.state = 'initialized'
+    return result
+}
+
+export async function openClientDocument(client, {filePath, text, languageId, version = 1}) {
+    if (client.state !== 'initialized') throw new Error('LSP client is not initialized')
+    if (typeof text !== 'string') throw new TypeError('document text must be a string')
+    if (typeof languageId !== 'string' || languageId === '') throw new TypeError('languageId is required')
+    if (!Number.isSafeInteger(version) || version < 0) {
+        throw new TypeError('document version must be a non-negative integer')
+    }
+    const normalized = client.normalizer.toUri(filePath)
+    await notifyClient(client, 'textDocument/didOpen', {
+        textDocument: {uri: normalized.uri, languageId, version, text},
+    })
+    client.openDocuments.set(normalized.uri, {file: normalized.file, version, languageId})
+    return {file: normalized.file, version, languageId}
+}
+
+export async function closeClientDocument(client, filePath) {
+    const normalized = client.normalizer.toUri(filePath)
+    if (!client.openDocuments.has(normalized.uri)) return false
+    await notifyClient(client, 'textDocument/didClose', {textDocument: {uri: normalized.uri}})
+    client.openDocuments.delete(normalized.uri)
+    return true
+}
+
+export function normalizeClientLocations(client, result) {
+    const locations = []
+    for (const raw of result == null ? [] : Array.isArray(result) ? result : [result]) {
+        if (raw == null || typeof raw !== 'object') continue
+        const uri = raw.uri || raw.targetUri
+        const range = raw.range || raw.targetSelectionRange || raw.targetRange
+        try {
+            const normalized = client.normalizer.fromUri(uri)
+            locations.push({file: normalized.file, range: normalizeRange(range)})
+        } catch (error) {
+            if (error instanceof RangeError) continue
+            throw error
+        }
+    }
+    return locations
+}
+
+export async function queryClientLocations(client, kind, {filePath, position, includeDeclaration = true, timeoutMs}) {
+    const normalized = client.normalizer.toUri(filePath)
+    const method = kind === 'references' ? 'textDocument/references' : 'textDocument/definition'
+    const params = {textDocument: {uri: normalized.uri}, position: assertPosition(position)}
+    if (kind === 'references') params.context = {includeDeclaration: Boolean(includeDeclaration)}
+    const result = await requestFromClient(client, method, params, {
+        timeoutMs: timeoutMs ?? client.requestTimeoutMs,
+    })
+    return normalizeClientLocations(client, result)
+}
+
+export async function defaultClientServerRequest(client, method, params) {
+    if (method === 'workspace/configuration') return Array.isArray(params?.items) ? params.items.map(() => null) : []
+    if (method === 'workspace/workspaceFolders') {
+        return [{uri: client.normalizer.rootUri, name: client.normalizer.rootPath.split(/[\\/]/).pop() || 'repository'}]
+    }
+    if (['client/registerCapability', 'client/unregisterCapability', 'window/workDoneProgress/create'].includes(method)) return null
+    if (method === 'workspace/applyEdit') {
+        return {applied: false, failureReason: 'Weavatrix precision provider is read-only'}
+    }
+    const error = new Error(`Unsupported LSP server request: ${method}`)
+    error.code = -32601
+    throw error
+}
+
+export async function handleClientServerRequest(client, message) {
+    try {
+        const result = client.onServerRequest
+            ? await client.onServerRequest(message.method, message.params, client)
+            : await defaultClientServerRequest(client, message.method, message.params)
+        await writeClientMessage(client, {jsonrpc: JSON_RPC_VERSION, id: message.id, result: result ?? null})
+    } catch (error) {
+        try {
+            await writeClientMessage(client, {
+                jsonrpc: JSON_RPC_VERSION,
+                id: message.id,
+                error: {
+                    code: Number.isInteger(error?.code) ? error.code : -32603,
+                    message: error?.message || 'LSP client error',
+                },
+            })
+        } catch { /* process exited while request handler was running */ }
+    }
+}
+
+export function handleClientMessage(client, message) {
+    if (message.jsonrpc !== JSON_RPC_VERSION) throw new LspProtocolError('Unsupported JSON-RPC version from LSP server')
+    if (typeof message.method === 'string') {
+        if (message.id != null) void handleClientServerRequest(client, message)
+        else client.onNotification?.(message.method, message.params, client)
+        return
+    }
+    if (message.id == null) throw new LspProtocolError('LSP response is missing an id')
+    const entry = client.pending.get(message.id)
+    if (!entry) return
+    client.pending.delete(message.id)
+    clearTimeout(entry.timer)
+    if (message.error != null) entry.reject(jsonRpcError(message.error))
+    else entry.resolve(message.result)
+}
+
+export function rejectPendingRequests(client, error) {
+    for (const entry of client.pending.values()) {
+        clearTimeout(entry.timer)
+        entry.reject(error)
+    }
+    client.pending.clear()
+}

package/src/precision/lsp-client/registry.js

@@ -0,0 +1,58 @@
+const ACTIVE_LSP_CLIENTS = new Set()
+let acceptingLspClients = true
+
+export function assertLspClientCreationAllowed() {
+    if (!acceptingLspClients) throw new Error('LSP process creation is disabled during MCP shutdown')
+}
+
+export function registerLspClient(client) {
+    ACTIVE_LSP_CLIENTS.add(client)
+}
+
+export function unregisterLspClient(client) {
+    ACTIVE_LSP_CLIENTS.delete(client)
+}
+
+export function isLspClientActive(client) {
+    return ACTIVE_LSP_CLIENTS.has(client)
+}
+
+export function activeLspClientCount() {
+    return ACTIVE_LSP_CLIENTS.size
+}
+
+export function beginLspClientShutdown() {
+    acceptingLspClients = false
+}
+
+export async function shutdownActiveLspClients({timeoutMs = 3_000} = {}) {
+    const boundedTimeout = Math.max(250, Math.min(10_000, Number(timeoutMs) || 3_000))
+    const startedAt = Date.now()
+    const clients = [...ACTIVE_LSP_CLIENTS]
+    if (!clients.length) return {requested: 0, remaining: 0, timedOut: false}
+    let timer
+    const gracefulBudget = Math.max(125, Math.floor(boundedTimeout * 0.6))
+    const graceful = Promise.allSettled(clients.map((client) => client.shutdown({timeoutMs: boundedTimeout})))
+    const outcome = await Promise.race([
+        graceful.then(() => 'closed'),
+        new Promise((resolveOutcome) => { timer = setTimeout(() => resolveOutcome('timeout'), gracefulBudget) }),
+    ])
+    if (timer) clearTimeout(timer)
+    const survivors = [...ACTIVE_LSP_CLIENTS]
+    if (survivors.length) {
+        const reason = new Error(`MCP shutdown timed out with ${ACTIVE_LSP_CLIENTS.size} active LSP client(s)`)
+        const forceBudget = Math.max(100, boundedTimeout - (Date.now() - startedAt))
+        await Promise.allSettled(survivors.map(async (client) => {
+            if (typeof client.killWindowsTreeAndWait === 'function') await client.killWindowsTreeAndWait(forceBudget)
+            client.kill(reason)
+            if (typeof client.waitForExit === 'function') {
+                await client.waitForExit(Math.max(100, boundedTimeout - (Date.now() - startedAt)))
+            }
+        }))
+    }
+    return {
+        requested: clients.length,
+        remaining: ACTIVE_LSP_CLIENTS.size,
+        timedOut: outcome === 'timeout' || ACTIVE_LSP_CLIENTS.size > 0,
+    }
+}

package/src/precision/lsp-client/repo-uri.js

@@ -0,0 +1,60 @@
+import {realpathSync} from 'node:fs'
+import {isAbsolute, relative, resolve, sep} from 'node:path'
+import {fileURLToPath, pathToFileURL} from 'node:url'
+
+function normalizeFilesystemPath(path) {
+    let normalized = path
+    if (process.platform === 'win32' && normalized.startsWith('\\\\?\\UNC\\')) normalized = `\\\\${normalized.slice(8)}`
+    else if (process.platform === 'win32' && normalized.startsWith('\\\\?\\')) normalized = normalized.slice(4)
+    return resolve(normalized)
+}
+
+function realpathIfPossible(path) {
+    try { return normalizeFilesystemPath(realpathSync.native(path)) }
+    catch { return normalizeFilesystemPath(path) }
+}
+
+function existingRealpath(path) {
+    try { return normalizeFilesystemPath(realpathSync.native(path)) }
+    catch { return null }
+}
+
+function pathInside(rootPath, candidatePath) {
+    const rel = relative(rootPath, candidatePath)
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
+}
+
+function portableRelative(rootPath, candidatePath) {
+    return relative(rootPath, candidatePath).split(sep).join('/')
+}
+
+/** Repository-bounded path/URI conversion surface used by the client. */
+export function createRepoUriNormalizer(repoRoot) {
+    if (typeof repoRoot !== 'string' || repoRoot.trim() === '') throw new TypeError('repoRoot is required')
+    const lexicalRoot = normalizeFilesystemPath(resolve(repoRoot))
+    const absoluteRoot = realpathIfPossible(lexicalRoot)
+    const toAbsolute = (filePath) => {
+        if (typeof filePath !== 'string' || filePath.trim() === '') throw new TypeError('filePath is required')
+        const lexicalPath = normalizeFilesystemPath(resolve(lexicalRoot, filePath))
+        const canonicalPath = existingRealpath(lexicalPath)
+        if (canonicalPath == null) {
+            if (!pathInside(lexicalRoot, lexicalPath)) throw new RangeError('LSP path is outside the repository')
+            return lexicalPath
+        }
+        if (!pathInside(absoluteRoot, canonicalPath)) throw new RangeError('LSP path resolves outside the repository')
+        return canonicalPath
+    }
+    const fromUri = (uri) => {
+        if (typeof uri !== 'string' || !uri.startsWith('file:')) throw new RangeError('Only file: LSP URIs are accepted')
+        let filePath
+        try { filePath = fileURLToPath(uri) }
+        catch (error) { throw new RangeError('Invalid file: LSP URI', {cause: error}) }
+        const absolutePath = toAbsolute(filePath)
+        return {file: portableRelative(absoluteRoot, absolutePath), absolutePath, uri: pathToFileURL(absolutePath).href}
+    }
+    const toUri = (filePath) => {
+        const absolutePath = toAbsolute(filePath)
+        return {file: portableRelative(absoluteRoot, absolutePath), absolutePath, uri: pathToFileURL(absolutePath).href}
+    }
+    return {rootPath: absoluteRoot, rootUri: pathToFileURL(absoluteRoot).href, toAbsolute, toUri, fromUri}
+}

package/src/precision/lsp-client/stdio-client.js

@@ -0,0 +1,151 @@
+import {spawn as spawnChild} from 'node:child_process'
+import {isAbsolute} from 'node:path'
+import {
+    DEFAULT_MAX_HEADER_BYTES,
+    DEFAULT_MAX_MESSAGE_BYTES,
+    DEFAULT_REQUEST_TIMEOUT_MS,
+    positiveInteger,
+} from './constants.js'
+import {lspChildProcessEnv} from './environment.js'
+import {ContentLengthMessageParser} from './message-parser.js'
+import {createRepoUriNormalizer} from './repo-uri.js'
+import {
+    assertLspClientCreationAllowed,
+    registerLspClient,
+    unregisterLspClient,
+} from './registry.js'
+import {
+    assertClientWritable,
+    closeClientDocument,
+    defaultClientServerRequest,
+    handleClientServerRequest,
+    handleClientMessage,
+    initializeClient,
+    normalizeClientLocations,
+    notifyClient,
+    openClientDocument,
+    queryClientLocations,
+    rejectPendingRequests,
+    requestFromClient,
+    writeClientMessage,
+} from './protocol.js'
+import {
+    failClient,
+    killClient,
+    killWindowsTreeAndWait,
+    shutdownClient,
+    shutdownClientOnce,
+    waitForClientExit,
+} from './lifecycle.js'
+
+export class StdioLspClient {
+    constructor({
+        repoRoot,
+        executablePath = process.execPath,
+        args = [],
+        env = {},
+        requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
+        maxMessageBytes = DEFAULT_MAX_MESSAGE_BYTES,
+        maxHeaderBytes = DEFAULT_MAX_HEADER_BYTES,
+        onNotification,
+        onServerRequest,
+        spawn = spawnChild,
+    } = {}) {
+        if (typeof executablePath !== 'string' || !isAbsolute(executablePath)) {
+            throw new TypeError('LSP executablePath must be absolute')
+        }
+        if (!Array.isArray(args) || args.some((arg) => typeof arg !== 'string')) {
+            throw new TypeError('LSP args must be strings')
+        }
+        if (typeof spawn !== 'function') throw new TypeError('spawn must be a function')
+        assertLspClientCreationAllowed()
+        this.normalizer = createRepoUriNormalizer(repoRoot)
+        this.requestTimeoutMs = positiveInteger(requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS, 'requestTimeoutMs')
+        this.maxMessageBytes = positiveInteger(maxMessageBytes, DEFAULT_MAX_MESSAGE_BYTES, 'maxMessageBytes')
+        this.onNotification = typeof onNotification === 'function' ? onNotification : null
+        this.onServerRequest = typeof onServerRequest === 'function' ? onServerRequest : null
+        this.pending = new Map()
+        this.openDocuments = new Map()
+        this.nextId = 1
+        this.state = 'starting'
+        this.stderrTail = ''
+        this.shutdownPromise = null
+        this.child = spawn(executablePath, args, {
+            cwd: this.normalizer.rootPath,
+            env: lspChildProcessEnv(env),
+            shell: false,
+            detached: process.platform !== 'win32',
+            windowsHide: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        })
+        this.processGroupPid = process.platform !== 'win32' && Number.isInteger(this.child.pid)
+            ? this.child.pid : null
+        registerLspClient(this)
+        this.parser = new ContentLengthMessageParser({
+            maxMessageBytes: this.maxMessageBytes,
+            maxHeaderBytes,
+            onMessage: (message) => this.handleMessage(message),
+        })
+        this.child.stdout?.on('data', (chunk) => {
+            try { this.parser.push(chunk) }
+            catch (error) { this.fail(error) }
+        })
+        this.child.stderr?.setEncoding('utf8')
+        this.child.stderr?.on('data', (chunk) => {
+            this.stderrTail = `${this.stderrTail}${chunk}`.slice(-16_000)
+        })
+        this.spawned = new Promise((resolveSpawn, rejectSpawn) => {
+            this.child.once('spawn', () => {
+                if (this.state === 'starting') this.state = 'running'
+                resolveSpawn(this)
+            })
+            this.child.once('error', (error) => {
+                this.fail(error)
+                rejectSpawn(error)
+            })
+        })
+        this.exited = new Promise((resolveExit) => {
+            let settled = false
+            const finishExit = (code, signal) => {
+                if (settled) return
+                settled = true
+                const wasStopping = this.state === 'stopping' || this.state === 'closed'
+                this.state = 'closed'
+                const suffix = this.stderrTail ? `\n${this.stderrTail}` : ''
+                this.rejectPending(new Error(`LSP server exited (code=${code}, signal=${signal})${suffix}`))
+                if (!wasStopping && code !== 0) this.openDocuments.clear()
+                unregisterLspClient(this)
+                resolveExit({code, signal})
+            }
+            this.child.once('exit', finishExit)
+            this.child.once('close', finishExit)
+        })
+    }
+
+    async start() { await this.spawned; return this }
+    assertWritable() { return assertClientWritable(this) }
+    writeMessage(message) { return writeClientMessage(this, message) }
+    request(method, params, options) { return requestFromClient(this, method, params, options) }
+    notify(method, params) { return notifyClient(this, method, params) }
+    initialize(options) { return initializeClient(this, options) }
+    openDocument(options) { return openClientDocument(this, options) }
+    closeDocument(filePath) { return closeClientDocument(this, filePath) }
+    normalizeLocations(result) { return normalizeClientLocations(this, result) }
+    definition(options) { return queryClientLocations(this, 'definition', options) }
+    references(options) { return queryClientLocations(this, 'references', options) }
+    defaultServerRequest(method, params) { return defaultClientServerRequest(this, method, params) }
+    handleServerRequest(message) { return handleClientServerRequest(this, message) }
+    handleMessage(message) { return handleClientMessage(this, message) }
+    rejectPending(error) { return rejectPendingRequests(this, error) }
+    fail(error) { return failClient(this, error) }
+    kill(reason) { return killClient(this, reason) }
+    killWindowsTreeAndWait(timeoutMs) { return killWindowsTreeAndWait(this, timeoutMs) }
+    waitForExit(timeoutMs) { return waitForClientExit(this, timeoutMs) }
+    shutdown(options) { return shutdownClient(this, options) }
+    shutdownOnce(options) { return shutdownClientOnce(this, options) }
+}
+
+export async function startStdioLspClient(options) {
+    const client = new StdioLspClient(options)
+    return client.start()
+}