@plaited/development-skills 0.3.5

package/src/lsp-analyze.ts

@@ -0,0 +1,223 @@
+#!/usr/bin/env bun
+/**
+ * Batch analysis script for TypeScript/JavaScript files
+ *
+ * Performs multiple LSP queries in a single session for efficiency.
+ * Useful for understanding a file before making changes.
+ *
+ * Usage: bun lsp-analyze.ts <file> [options]
+ *
+ * Options:
+ *   --symbols, -s       List all symbols in the file
+ *   --exports, -e       List only exported symbols
+ *   --hover <line:char> Get type info at position (can be repeated)
+ *   --refs <line:char>  Find references at position (can be repeated)
+ *   --all               Run all analyses (symbols + exports)
+ */
+
+import { parseArgs } from 'node:util'
+import { LspClient } from './lsp-client.ts'
+import { resolveFilePath } from './resolve-file-path.ts'
+
+type SymbolInfo = {
+  name: string
+  kind: number
+  range: { start: { line: number; character: number }; end: { line: number; character: number } }
+  children?: SymbolInfo[]
+}
+
+type AnalysisResult = {
+  file: string
+  symbols?: Array<{ name: string; kind: string; line: number }>
+  exports?: Array<{ name: string; kind: string; line: number }>
+  hovers?: Array<{ position: string; content: unknown }>
+  references?: Array<{ position: string; locations: unknown }>
+}
+
+const symbolKindNames: Record<number, string> = {
+  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: 'EnumMember',
+  23: 'Struct',
+  24: 'Event',
+  25: 'Operator',
+  26: 'TypeParameter',
+}
+
+const extractSymbols = (symbols: SymbolInfo[], prefix = ''): Array<{ name: string; kind: string; line: number }> => {
+  const result: Array<{ name: string; kind: string; line: number }> = []
+  for (const sym of symbols) {
+    result.push({
+      name: prefix ? `${prefix}.${sym.name}` : sym.name,
+      kind: symbolKindNames[sym.kind] || `Unknown(${sym.kind})`,
+      line: sym.range.start.line,
+    })
+    if (sym.children) {
+      result.push(...extractSymbols(sym.children, sym.name))
+    }
+  }
+  return result
+}
+
+/**
+ * Batch analysis for TypeScript/JavaScript files
+ *
+ * @param args - Command line arguments
+ */
+export const lspAnalyze = async (args: string[]) => {
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      symbols: { type: 'boolean', short: 's' },
+      exports: { type: 'boolean', short: 'e' },
+      hover: { type: 'string', multiple: true },
+      refs: { type: 'string', multiple: true },
+      all: { type: 'boolean' },
+      help: { type: 'boolean', short: 'h' },
+    },
+    allowPositionals: true,
+  })
+
+  if (values.help || positionals.length === 0) {
+    console.log(`
+LSP Analyze - Batch analysis for TypeScript/JavaScript files
+
+Usage: lsp-analyze <file> [options]
+
+Options:
+  --symbols, -s       List all symbols in the file
+  --exports, -e       List only exported symbols
+  --hover <line:char> Get type info at position (can be repeated)
+  --refs <line:char>  Find references at position (can be repeated)
+  --all               Run all analyses (symbols + exports)
+  --help, -h          Show this help
+
+Examples:
+  lsp-analyze src/app.ts --all
+  lsp-analyze src/app.ts --symbols
+  lsp-analyze src/app.ts --hover 50:15 --hover 60:20
+  lsp-analyze src/app.ts --refs 10:8
+`)
+    process.exit(0)
+  }
+
+  const filePath = positionals[0]
+  if (!filePath) {
+    console.error('Error: File path required')
+    process.exit(1)
+  }
+  const absolutePath = await resolveFilePath(filePath)
+  const uri = `file://${absolutePath}`
+  const rootUri = `file://${process.cwd()}`
+
+  const client = new LspClient({ rootUri })
+
+  try {
+    await client.start()
+
+    const file = Bun.file(absolutePath)
+    if (!(await file.exists())) {
+      console.error(`Error: File not found: ${absolutePath}`)
+      process.exit(1)
+    }
+
+    const text = await file.text()
+    const languageId = absolutePath.endsWith('.tsx')
+      ? 'typescriptreact'
+      : absolutePath.endsWith('.ts')
+        ? 'typescript'
+        : absolutePath.endsWith('.jsx')
+          ? 'javascriptreact'
+          : 'javascript'
+
+    client.openDocument(uri, languageId, 1, text)
+
+    const result: AnalysisResult = { file: filePath }
+
+    // Get symbols if requested
+    if (values.symbols || values.exports || values.all) {
+      const symbols = (await client.documentSymbols(uri)) as SymbolInfo[]
+      const extracted = extractSymbols(symbols)
+
+      if (values.symbols || values.all) {
+        result.symbols = extracted
+      }
+
+      if (values.exports || values.all) {
+        // Filter to only top-level exports (items that start with export in source)
+        const lines = text.split('\n')
+        result.exports = extracted.filter((sym) => {
+          const line = lines[sym.line]
+          return line?.includes('export')
+        })
+      }
+    }
+
+    // Get hover info if requested
+    if (values.hover?.length) {
+      result.hovers = []
+      for (const pos of values.hover) {
+        const parts = pos.split(':')
+        const lineStr = parts[0] ?? ''
+        const charStr = parts[1] ?? ''
+        const line = parseInt(lineStr, 10)
+        const char = parseInt(charStr, 10)
+
+        if (!Number.isNaN(line) && !Number.isNaN(char)) {
+          const hover = await client.hover(uri, line, char)
+          result.hovers.push({ position: pos, content: hover })
+        }
+      }
+    }
+
+    // Get references if requested
+    if (values.refs?.length) {
+      result.references = []
+      for (const pos of values.refs) {
+        const parts = pos.split(':')
+        const lineStr = parts[0] ?? ''
+        const charStr = parts[1] ?? ''
+        const line = parseInt(lineStr, 10)
+        const char = parseInt(charStr, 10)
+
+        if (!Number.isNaN(line) && !Number.isNaN(char)) {
+          const refs = await client.references(uri, line, char, true)
+          result.references.push({ position: pos, locations: refs })
+        }
+      }
+    }
+
+    client.closeDocument(uri)
+    await client.stop()
+
+    console.log(JSON.stringify(result, null, 2))
+  } catch (error) {
+    console.error(`Error: ${error}`)
+    await client.stop()
+    process.exit(1)
+  }
+}
+
+// Keep executable entry point for direct execution
+if (import.meta.main) {
+  await lspAnalyze(Bun.argv.slice(2))
+}

package/src/lsp-client.ts

@@ -0,0 +1,400 @@
+/**
+ * TypeScript Language Server client using Bun.spawn
+ *
+ * @remarks
+ * Spawns typescript-language-server as a subprocess and communicates via LSP JSON-RPC protocol.
+ * Uses Bun's native spawn API for process management.
+ *
+ * @internal
+ */
+
+import type { Subprocess } from 'bun'
+
+type JsonRpcRequest = {
+  jsonrpc: '2.0'
+  id: number
+  method: string
+  params?: unknown
+}
+
+type JsonRpcResponse = {
+  jsonrpc: '2.0'
+  id: number
+  result?: unknown
+  error?: { code: number; message: string; data?: unknown }
+}
+
+type JsonRpcNotification = {
+  jsonrpc: '2.0'
+  method: string
+  params?: unknown
+}
+
+type PendingRequest = {
+  resolve: (value: unknown) => void
+  reject: (error: Error) => void
+  timer?: ReturnType<typeof setTimeout>
+}
+
+/**
+ * LSP Client that manages a typescript-language-server subprocess
+ */
+export class LspClient {
+  #process: Subprocess | null = null
+  #requestId = 0
+  #pendingRequests = new Map<number, PendingRequest>()
+  #buffer = new Uint8Array(0)
+  #contentLength = -1
+  #initialized = false
+  #rootUri: string
+  #serverCommand: string[]
+  #requestTimeout: number
+
+  constructor({
+    rootUri,
+    command = ['bun', 'typescript-language-server', '--stdio'],
+    requestTimeout = 30000,
+  }: {
+    rootUri: string
+    command?: string[]
+    requestTimeout?: number
+  }) {
+    this.#rootUri = rootUri
+    this.#serverCommand = command
+    this.#requestTimeout = requestTimeout
+  }
+
+  /**
+   * Start the LSP server subprocess
+   */
+  async start(): Promise<void> {
+    if (this.#process) {
+      throw new Error('LSP server already running')
+    }
+
+    this.#process = Bun.spawn(this.#serverCommand, {
+      stdin: 'pipe',
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+
+    // Start reading stdout
+    this.#readOutput()
+
+    // Initialize the LSP connection
+    await this.#initialize()
+  }
+
+  /**
+   * Stop the LSP server subprocess
+   */
+  async stop(): Promise<void> {
+    if (!this.#process) return
+
+    // Send shutdown request
+    try {
+      await this.request('shutdown', null)
+      this.notify('exit')
+    } catch {
+      // Ignore errors during shutdown
+    }
+
+    this.#process.kill()
+    this.#process = null
+    this.#initialized = false
+  }
+
+  /**
+   * Check if the LSP server is running
+   */
+  isRunning(): boolean {
+    return this.#process !== null && this.#initialized
+  }
+
+  /**
+   * Send a request to the LSP server and wait for response
+   */
+  async request<T = unknown>(method: string, params: unknown): Promise<T> {
+    if (!this.#process) {
+      throw new Error('LSP server not running')
+    }
+
+    this.#requestId += 1
+    const id = this.#requestId
+    const request: JsonRpcRequest = {
+      jsonrpc: '2.0',
+      id,
+      method,
+      params: params ?? undefined,
+    }
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pendingRequests.delete(id)
+        reject(new Error(`LSP request timeout: ${method} (id=${id})`))
+      }, this.#requestTimeout)
+
+      this.#pendingRequests.set(id, {
+        resolve: resolve as (value: unknown) => void,
+        reject,
+        timer,
+      })
+      this.#send(request)
+    })
+  }
+
+  /**
+   * Send a notification to the LSP server (no response expected)
+   */
+  notify(method: string, params?: unknown): void {
+    if (!this.#process) {
+      throw new Error('LSP server not running')
+    }
+
+    const notification: JsonRpcNotification = {
+      jsonrpc: '2.0',
+      method,
+      params,
+    }
+
+    this.#send(notification)
+  }
+
+  // LSP Methods
+
+  /**
+   * textDocument/hover - Get hover information at a position
+   */
+  async hover(uri: string, line: number, character: number): Promise<unknown> {
+    return this.request('textDocument/hover', {
+      textDocument: { uri },
+      position: { line, character },
+    })
+  }
+
+  /**
+   * textDocument/definition - Go to definition
+   */
+  async definition(uri: string, line: number, character: number): Promise<unknown> {
+    return this.request('textDocument/definition', {
+      textDocument: { uri },
+      position: { line, character },
+    })
+  }
+
+  /**
+   * textDocument/references - Find all references
+   */
+  async references(uri: string, line: number, character: number, includeDeclaration = true): Promise<unknown> {
+    return this.request('textDocument/references', {
+      textDocument: { uri },
+      position: { line, character },
+      context: { includeDeclaration },
+    })
+  }
+
+  /**
+   * textDocument/completion - Get completions at a position
+   */
+  async completion(uri: string, line: number, character: number): Promise<unknown> {
+    return this.request('textDocument/completion', {
+      textDocument: { uri },
+      position: { line, character },
+    })
+  }
+
+  /**
+   * textDocument/signatureHelp - Get signature help
+   */
+  async signatureHelp(uri: string, line: number, character: number): Promise<unknown> {
+    return this.request('textDocument/signatureHelp', {
+      textDocument: { uri },
+      position: { line, character },
+    })
+  }
+
+  /**
+   * textDocument/documentSymbol - Get document symbols
+   */
+  async documentSymbols(uri: string): Promise<unknown> {
+    return this.request('textDocument/documentSymbol', {
+      textDocument: { uri },
+    })
+  }
+
+  /**
+   * workspace/symbol - Search for symbols across workspace
+   */
+  async workspaceSymbols(query: string): Promise<unknown> {
+    return this.request('workspace/symbol', { query })
+  }
+
+  /**
+   * Open a document in the LSP server
+   */
+  openDocument(uri: string, languageId: string, version: number, text: string): void {
+    this.notify('textDocument/didOpen', {
+      textDocument: {
+        uri,
+        languageId,
+        version,
+        text,
+      },
+    })
+  }
+
+  /**
+   * Close a document in the LSP server
+   */
+  closeDocument(uri: string): void {
+    this.notify('textDocument/didClose', {
+      textDocument: { uri },
+    })
+  }
+
+  async #initialize(): Promise<void> {
+    const result = await this.request('initialize', {
+      processId: process.pid,
+      rootUri: this.#rootUri,
+      capabilities: {
+        textDocument: {
+          hover: { contentFormat: ['markdown', 'plaintext'] },
+          definition: { linkSupport: true },
+          references: {},
+          completion: {
+            completionItem: {
+              snippetSupport: true,
+              documentationFormat: ['markdown', 'plaintext'],
+            },
+          },
+          signatureHelp: {
+            signatureInformation: {
+              documentationFormat: ['markdown', 'plaintext'],
+            },
+          },
+          documentSymbol: {
+            hierarchicalDocumentSymbolSupport: true,
+          },
+        },
+        workspace: {
+          symbol: { symbolKind: {} },
+        },
+      },
+    })
+
+    this.notify('initialized', {})
+    this.#initialized = true
+
+    return result as Promise<void>
+  }
+
+  #send(message: JsonRpcRequest | JsonRpcNotification): void {
+    const stdin = this.#process?.stdin
+    if (!stdin || typeof stdin === 'number') {
+      throw new Error('LSP server stdin not available')
+    }
+
+    const content = JSON.stringify(message)
+    const header = `Content-Length: ${Buffer.byteLength(content)}\r\n\r\n`
+
+    stdin.write(header + content)
+  }
+
+  async #readOutput(): Promise<void> {
+    const stdout = this.#process?.stdout
+    if (!stdout || typeof stdout === 'number') return
+
+    const reader = stdout.getReader()
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+
+        // Append new bytes to buffer
+        const newBuffer = new Uint8Array(this.#buffer.length + value.length)
+        newBuffer.set(this.#buffer)
+        newBuffer.set(value, this.#buffer.length)
+        this.#buffer = newBuffer
+
+        this.#processBuffer()
+      }
+    } catch {
+      // Stream closed
+    }
+  }
+
+  #processBuffer(): void {
+    const decoder = new TextDecoder()
+
+    while (true) {
+      // Parse header if we don't have content length yet
+      if (this.#contentLength === -1) {
+        // Look for header end sequence: \r\n\r\n
+        const headerEndIndex = this.#findHeaderEnd()
+        if (headerEndIndex === -1) break
+
+        const headerBytes = this.#buffer.slice(0, headerEndIndex)
+        const header = decoder.decode(headerBytes)
+        const match = header.match(/Content-Length: (\d+)/)
+        if (!match?.[1]) {
+          // Skip invalid header
+          this.#buffer = this.#buffer.slice(headerEndIndex + 4)
+          continue
+        }
+
+        this.#contentLength = parseInt(match[1], 10)
+        this.#buffer = this.#buffer.slice(headerEndIndex + 4)
+      }
+
+      // Check if we have enough content (now comparing bytes to bytes)
+      if (this.#buffer.length < this.#contentLength) break
+
+      const contentBytes = this.#buffer.slice(0, this.#contentLength)
+      const content = decoder.decode(contentBytes)
+      this.#buffer = this.#buffer.slice(this.#contentLength)
+      this.#contentLength = -1
+
+      try {
+        const message = JSON.parse(content) as JsonRpcResponse
+        this.#handleMessage(message)
+      } catch {
+        // Skip invalid JSON
+      }
+    }
+  }
+
+  #findHeaderEnd(): number {
+    // Look for \r\n\r\n sequence in buffer
+    const CRLF = [13, 10, 13, 10] // \r\n\r\n
+    for (let i = 0; i <= this.#buffer.length - 4; i++) {
+      if (
+        this.#buffer[i] === CRLF[0] &&
+        this.#buffer[i + 1] === CRLF[1] &&
+        this.#buffer[i + 2] === CRLF[2] &&
+        this.#buffer[i + 3] === CRLF[3]
+      ) {
+        return i
+      }
+    }
+    return -1
+  }
+
+  #handleMessage(message: JsonRpcResponse): void {
+    if ('id' in message && message.id !== undefined) {
+      const pending = this.#pendingRequests.get(message.id)
+      if (pending) {
+        if (pending.timer) {
+          clearTimeout(pending.timer)
+        }
+        this.#pendingRequests.delete(message.id)
+        if (message.error) {
+          pending.reject(new Error(`LSP Error: ${message.error.message}`))
+        } else {
+          pending.resolve(message.result)
+        }
+      }
+    }
+    // Notifications and server requests are ignored for now
+  }
+}

package/src/lsp-find.ts

@@ -0,0 +1,100 @@
+#!/usr/bin/env bun
+/**
+ * Search for symbols across the workspace by name
+ *
+ * Usage: bun lsp-find.ts <query> [file]
+ */
+
+import { parseArgs } from 'node:util'
+import { LspClient } from './lsp-client.ts'
+import { resolveFilePath } from './resolve-file-path.ts'
+
+/**
+ * Find a default context file when none is provided
+ *
+ * @remarks
+ * Checks common TypeScript entry points in order of preference
+ */
+const findDefaultContextFile = async (): Promise<string | null> => {
+  const candidates = [`${process.cwd()}/src/index.ts`, `${process.cwd()}/src/main.ts`, `${process.cwd()}/index.ts`]
+  for (const candidate of candidates) {
+    if (await Bun.file(candidate).exists()) {
+      return candidate
+    }
+  }
+  return null
+}
+
+/**
+ * Search for symbols across the workspace by name
+ *
+ * @param args - Command line arguments [query, file?]
+ */
+export const lspFind = async (args: string[]) => {
+  const { positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+  })
+
+  const [query, filePath] = positionals
+
+  if (!query) {
+    console.error('Usage: lsp-find <query> [file]')
+    console.error('  query: Symbol name or partial name to search')
+    console.error('  file: Optional file to open for project context')
+    process.exit(1)
+  }
+
+  const rootUri = `file://${process.cwd()}`
+  const client = new LspClient({ rootUri })
+
+  try {
+    await client.start()
+
+    // Open a file to establish project context if provided, otherwise find a default
+    const contextFile = filePath ? await resolveFilePath(filePath) : await findDefaultContextFile()
+
+    if (!contextFile) {
+      console.error('Error: No context file found.')
+      console.error('Provide a file path or ensure src/index.ts, src/main.ts, or index.ts exists.')
+      await client.stop()
+      process.exit(1)
+    }
+
+    const file = Bun.file(contextFile)
+    if (!(await file.exists())) {
+      console.error(`Error: Context file not found: ${contextFile}`)
+      console.error('Workspace symbol search requires at least one open document.')
+      await client.stop()
+      process.exit(1)
+    }
+
+    const text = await file.text()
+    const uri = `file://${contextFile}`
+    const languageId = contextFile.endsWith('.tsx')
+      ? 'typescriptreact'
+      : contextFile.endsWith('.ts')
+        ? 'typescript'
+        : contextFile.endsWith('.jsx')
+          ? 'javascriptreact'
+          : 'javascript'
+
+    client.openDocument(uri, languageId, 1, text)
+
+    const result = await client.workspaceSymbols(query)
+
+    client.closeDocument(uri)
+    await client.stop()
+
+    console.log(JSON.stringify(result, null, 2))
+  } catch (error) {
+    console.error(`Error: ${error}`)
+    await client.stop()
+    process.exit(1)
+  }
+}
+
+// Keep executable entry point for direct execution
+if (import.meta.main) {
+  await lspFind(Bun.argv.slice(2))
+}