Claude Code subagent imported from Ramilito/kubectl.nvim (.claude/agents/lsp.md). Copyright stays with the author.

LSP Features Guidance

ALWAYS use this subagent for ANY task involving:

• LSP server configuration or capabilities
• Completion sources for different filetypes
• Hover provider (resource info display)
• Diagnostics (errors/warnings for resources)
• Adding new completion sources or hover formatters

For general Lua/Neovim patterns, use the lua subagent. For Rust async patterns and mlua FFI, use the rust subagent.

Architecture Overview

The plugin runs an in-process LSP server (no external process). This enables:

• Native completion via vim.lsp.completion or external plugins (blink.cmp, nvim-cmp)
• Hover information via vim.lsp.buf.hover() (typically K key)
• Diagnostics for resource status issues

+-------------------------------------------------------------+
|                         Neovim                               |
|  +-----------------+      +----------------------------+    |
|  | Plugin Buffers  |<---->|  kubectl LSP Server        |    |
|  | (k8s_* types)   |      |  (in-process, lsp/init.lua)|    |
|  +-----------------+      +----------------------------+    |
|           |                          |                       |
|           v                          v                       |
|  +-----------------+      +----------------------------+    |
|  | Diagnostics     |      |  Handlers:                 |    |
|  | (virtual_lines) |      |  - completion -> sources/* |    |
|  +-----------------+      |  - hover -> Rust FFI       |    |
|                           +----------------------------+    |
+-------------------------------------------------------------+

File Map

Data Flow

Completion Flow

User types in prompt buffer
        |
        v
LSP textDocument/completion request
        |
        v
lsp/init.lua:get_completion_items()
        |
        v
sources[filetype]() -> items[]
        |
        v
Return to LSP client (displayed by completion plugin)

Hover Flow

User triggers hover (K key)
        |
        v
LSP textDocument/hover request
        |
        v
lsp/hover/init.lua:get_hover()
        |
        +--> resource_from_filetype() -> resource name
        +--> get_selection() -> name, namespace
        |
        v
commands.run_async("get_hover_async", {gvk, namespace, name})
        |
        v
Rust: hover/mod.rs -> store cache or API fetch
        |
        v
Rust: formatters.rs -> markdown output
        |
        v
Lua: append diagnostic section (if any)
        |
        v
Return markdown to Neovim hover window

Diagnostics Flow

Resource view drawn (via resource_factory)
        |
        v
diagnostics.set_diagnostics(bufnr, resource)
        |
        v
Iterate builder.processedData rows
        |
        +--> Check status/phase/conditions for severity symbols
        +--> Build message from status, ready, restarts, hint
        |
        v
vim.diagnostic.set(ns, bufnr, diagnostics)
        |
        v
Displayed via virtual_lines (current line only by default)

LSP Server Implementation

The server is created in lsp/init.lua:8-49 as a Lua function (not an external process):

local function server(opts)
  return function(dispatchers)
    local srv = {}

    function srv.request(method, params, callback)
      local handler = handlers[method]
      if handler then
        handler(method, params, callback)
      elseif method == "initialize" then
        callback(nil, { capabilities = capabilities })
      end
      -- ...
    end

    return srv
  end
end

Capabilities declared (line 76-80):

• completionProvider with trigger characters :, -
• hoverProvider = true

Client reuse: Same client attached to all k8s_* buffers via reuse_client (line 69-71).

Completion Sources

Each source follows the pattern:

local M = {}

function M.get_items()
  local items = {}
  -- Build completion items
  return items
end

function M.register()
  require("kubectl.lsp").register_source("k8s_<filetype>", M.get_items)
end

return M

Completion item fields:

• label - Display text
• labelDetails.description - Secondary info (kind name, etc.)
• insertText - Text to insert (if different from label)
• documentation - Hover docs for item
• kind_name / kind_icon - Custom kind display

Registered sources:

Hover Provider

lsp/hover/init.lua handles textDocument/hover:

1. Filetype check (resource_from_filetype) - Skips non-resource views (filter, namespaces, yaml, describe)
2. Selection extraction (get_selection) - Gets name/namespace using column positions from definition
3. Async fetch - Calls Rust get_hover_async with GVK and identifiers
4. Diagnostic append (get_diagnostic_section) - Adds diagnostics for current line if any

Rust Hover Formatters

hover/formatters.rs has resource-specific formatters for 15 resource types:

Output format: Markdown with ## headers, **bold** labels, `code` for values.

Diagnostics

lsp/diagnostics/init.lua provides Kubernetes-aware diagnostics:

Severity detection (line 10-11):

local error_symbols = { KubectlError = vim.diagnostic.severity.ERROR }
local warning_symbols = { KubectlWarning = vim.diagnostic.severity.WARN }

These symbols come from Rust processors (status.symbol field).

Message building (get_message, line 49-99):

• Status value with hint from Rust (if unhealthy)
• Ready count (if not all ready)
• Restart count with context
• Age (for errors only)

Display config (line 176-184):

vim.diagnostic.config({
  virtual_text = false,
  virtual_lines = { current_line = true },  -- Only show on current line
  signs = true,
  underline = false,
})

Public API:

• M.set_diagnostics(bufnr, resource) - Called after view draw
• M.toggle() - Enable/disable virtual_lines display
• M.to_quickfix() - Export to quickfix list

Common Tasks

Adding a New Completion Source

1. Create lua/kubectl/lsp/sources/<name>.lua:

local M = {}

function M.get_items()
  local items = {}
  -- Fetch data and build items
  table.insert(items, {
    label = "item-name",
    kind_name = "KindName",
    kind_icon = "...",
  })
  return items
end

function M.register()
  require("kubectl.lsp").register_source("k8s_<filetype>", M.get_items)
end

return M

2. Register in plugin initialization (typically in init.lua setup)

Adding Hover for New Resource Type

1. Add case in hover/formatters.rs:format_resource():

"myresource" | "myresources" => format_myresource(obj),

2. Implement formatter function following existing patterns:

fn format_myresource(obj: &DynamicObject) -> String {
    let Ok(res) = from_value::<MyResource>(to_value(obj).unwrap_or_default()) else {
        return format_generic("MyResource", obj);
    };
    // Build markdown lines...
}

Adding Diagnostic Severity

1. Add symbol mapping in diagnostics/init.lua:

local error_symbols = { KubectlError = ..., MyNewErrorSymbol = ... }

2. Ensure Rust processor sets status.symbol to match

Extending Diagnostic Message

Modify get_message() in diagnostics/init.lua to include new fields:

if row.my_field then
  local val = get_value(row.my_field)
  if val ~= "" then
    table.insert(parts, string.format("My Field: %s", val))
  end
end

Testing

Manual testing via:

nvim -u repro.lua

Then:

• Open :Kubectl pods - verify diagnostics appear on unhealthy pods
• Press K on a pod row - verify hover shows resource info
• Open :Kubectl and type - verify completion shows resources
• Open :Kubens and type - verify namespace completion

Key Patterns

1. In-process LSP - No subprocess, server is a Lua table with request/notify methods
2. Filetype-based sources - sources[filetype]() pattern for completion dispatch
3. Async hover - Rust fetch with vim.schedule callback for UI safety
4. Symbol-based severity - Rust processors set symbol field, Lua maps to severity
5. Virtual lines - Diagnostics shown inline only on current line to reduce noise