tools-lsp-tree-sitter

name

tools-lsp-tree-sitter

description

Gather resolved semantic evidence with LSP and syntax fallback with tree-sitter. Use when architecture findings need actual definitions, references, callers, implementations, diagnostics, or symbols rather than text matches — especially for coupling and boundary claims. Use tree-sitter when no language server is available or the question is purely syntactic. NOT for exact text discovery (use tools-code-search), repo-scale dependency graphs (use tools-codegraph), or git history (use tools-gitnexus).

LSP and tree-sitter

A language server resolves symbols the way the compiler does: it knows the real definition, every reference, the implementations of an interface, and the diagnostics the toolchain reports. tree-sitter parses syntax without resolution — fast, language-agnostic, but it cannot tell you what a name resolves to. Reach for LSP when you need semantic truth; fall back to tree-sitter when no server is configured.

Evidence dimensions: semantic (LSP) and structural (tree-sitter).

When to use

Use LSP to confirm a real call/reference relationship before claiming coupling, to find every implementation of a boundary interface, to verify callers/callees at a seam, and to surface compiler diagnostics. Use tree-sitter syntax queries when LSP is unavailable or when the question is purely syntactic (find all functions, all type declarations) and a server would be overkill.

Commands

LSP access depends on the runtime's LSP integration; use only exposed runtime operations, and do not invent tool names. Operations to request:

definition <file>:<line>:<col>     # where a symbol is defined
references <file>:<line>:<col>     # every use of a symbol
implementations <symbol>           # implementors of an interface/abstract type
diagnostics <file|workspace>       # compiler/linter diagnostics
documentSymbols <file>             # outline of one file
workspaceSymbols <query>           # find a symbol across the project

tree-sitter syntax queries (no resolution, pattern over the parse tree):

# Function definitions (Python grammar)
tree-sitter query func.scm src/**/*.py

# Inline: capture all class declarations
tree-sitter parse src/foo.py            # inspect the tree to write a query

A .scm query file holds the capture patterns; run it across the target files.

Evidence output

Record:

• dimension: semantic for LSP, structural for tree-sitter.
• source: operation, file:line:col or query file, and project/build context.
• facts: definitions, references, implementations, diagnostics, symbols, or syntax matches.
• limits: missing server, non-building project, partial workspace, or syntax-only fallback.

Confidence impact

• An LSP references/implementations result is the strongest structural- semantic evidence available — it reflects real resolution. tools_used, raises confidence for boundary and coupling findings ("X is referenced only from Y" is a resolved fact, not a guess).
• tree-sitter answers syntactic questions only; a tree-sitter match is the same strength as an ast-grep match (presence, not reachability). Don't claim "no callers" from tree-sitter — that needs LSP references or the codegraph.

Failure and missing-tool handling

• No language server for the language → semantic dimension tools_missing; fall back to tree-sitter (syntactic) plus tools-codegraph (graph) and record the reduced semantic coverage. A claim that needs resolution but has only syntactic evidence must be flagged as a hypothesis, not a fact.
• LSP returns nothing because the project doesn't build (missing deps, broken config) → that's tools_failed, not "no references." Note the build state and cap confidence.

When to stop

Resolve the specific relationship the finding rests on, then stop. Don't pull references for every symbol in the module — only the ones a score depends on. When you need aggregate graph shape (all cycles, all hubs) rather than one symbol's neighborhood, switch to tools-codegraph instead of fanning out LSP queries.

Hard rules

• A "no callers / no references" claim requires LSP resolution or the code graph — never assert it from syntax alone.
• LSP emptiness from a non-building project is tools_failed, not evidence.
• Do not embed a parser in package code — use the runtime's LSP/tree-sitter integration.