treesitter

Documentation

Overview

Package treesitter provides in-process AST parsing and structural code search using tree-sitter grammars. It supports multiple languages and provides pattern-based code matching.

Uses the pure Go tree-sitter implementation (gotreesitter), which requires no CGO and works on all platforms including cross-compilation.

Index

• func GetLanguage(name string) *gotreesitter.Language
• func IsSupported(name string) bool
• func SupportedLanguages() []string
• func WalkNodes(node *gotreesitter.Node, lang *gotreesitter.Language, ...)
• type Impact
  • func Analyze(ctx context.Context, parser *Parser, symbol, targetFile, workspaceRoot string) ([]Impact, error)
• type Match
  • func Search(ctx context.Context, parser *Parser, source []byte, lang, pattern, file string) ([]Match, error)
  • func SearchText(ctx context.Context, parser *Parser, source []byte, lang, pattern, file string) ([]Match, error)
• type Parser
  • func NewParser() *Parser
  • func (p *Parser) ExtractSymbols(tree *Tree, file string) []Symbol
  • func (p *Parser) Parse(_ context.Context, source []byte, lang string) (*Tree, error)
• type Symbol
  • func ExtractSymbols(tree *Tree, file string) []Symbol
• type Tree

Functions

func GetLanguage

func GetLanguage(name string) *gotreesitter.Language

GetLanguage returns the tree-sitter language for the given name or alias. Returns nil if the language is not supported.

func IsSupported

func IsSupported(name string) bool

IsSupported returns true if the given language name or alias is supported.

func SupportedLanguages

func SupportedLanguages() []string

SupportedLanguages returns all supported language names.

func WalkNodes

func WalkNodes(node *gotreesitter.Node, lang *gotreesitter.Language, fn func(*gotreesitter.Node) bool)

WalkNodes calls fn for every node in the tree (depth-first).

Types

type Impact

type Impact struct {
	Symbol   string `json:"symbol"`   // the affected symbol name
	File     string `json:"file"`     // file containing the affected symbol
	Line     int    `json:"line"`     // line number
	Kind     string `json:"kind"`     // "calls", "called_by", "references"
	Distance int    `json:"distance"` // hops from the target symbol
	Context  string `json:"context"`  // surrounding code context
}

Impact represents a dependency relationship found during impact analysis.

func Analyze

func Analyze(ctx context.Context, parser *Parser, symbol, targetFile, workspaceRoot string) ([]Impact, error)

Analyze performs impact analysis: given a symbol name and file, finds all callers and references across the workspace.

This is a simplified version that searches for the symbol name in all source files within the workspace. For full cross-file analysis with accurate AST matching, use the RefGraph from the indexer package.

type Match

type Match struct {
	File        string            `json:"file"`
	StartLine   int               `json:"start_line"`
	EndLine     int               `json:"end_line"`
	StartCol    int               `json:"start_col"`
	EndCol      int               `json:"end_col"`
	MatchedCode string            `json:"matched_code"`
	Captures    map[string]string `json:"captures,omitempty"`
}

Match represents a structural code match.

func Search

func Search(ctx context.Context, parser *Parser, source []byte, lang, pattern, file string) ([]Match, error)

Search performs a structural search on the given source code using a tree-sitter query pattern. The pattern should be a tree-sitter S-expression query.

For convenience, simple patterns are also supported:

• Node type matching: "(function_declaration)" finds all functions
• Named captures: "(function_declaration name: (identifier) @name)"
• Predicates: '#eq?' for exact matching

func SearchText

func SearchText(ctx context.Context, parser *Parser, source []byte, lang, pattern, file string) ([]Match, error)

SearchText performs a structural search using an ast-grep-style text pattern. It translates common patterns to tree-sitter queries where possible.

Pattern syntax (subset of ast-grep):

• Literal code: matched structurally against the AST
• $NAME: matches any single AST node
• $$$: matches zero or more AST nodes

Note: Full ast-grep pattern translation is complex. This function provides basic support; for full ast-grep patterns, use the container fallback.

type Parser

type Parser struct {
	// contains filtered or unexported fields
}

Parser wraps tree-sitter parsing for multiple languages.

func NewParser

func NewParser() *Parser

NewParser creates a new tree-sitter parser.

func (*Parser) ExtractSymbols

func (p *Parser) ExtractSymbols(tree *Tree, file string) []Symbol

ExtractSymbols returns top-level definition symbols using the upstream tree-sitter Tagger. Signature is the real declaration header from source (everything from the start of the tagged span up to the body delimiter), not a synthesized "<kind> <name>" string.

Supplemental walkers (walkSupplementalSymbols) cover languages where the upstream tagger has gaps: TypeScript type-alias declarations and Ruby (which has no upstream tags query at all today).

func (*Parser) Parse

func (p *Parser) Parse(_ context.Context, source []byte, lang string) (*Tree, error)

Parse parses source code in the given language and returns the AST.

type Symbol

type Symbol struct {
	Name      string `json:"name"`
	Kind      string `json:"kind"`      // func, type, interface, method, class, const, var
	Signature string `json:"signature"` // human-readable signature
	File      string `json:"file"`      // relative path
	Line      int    `json:"line"`
	Exported  bool   `json:"exported"`
}

Symbol represents a top-level code symbol extracted from an AST.

func ExtractSymbols

func ExtractSymbols(tree *Tree, file string) []Symbol

ExtractSymbols extracts top-level symbols from a parsed tree.

Convenience wrapper around (*Parser).ExtractSymbols for callers that don't already hold a Parser. Allocates a one-shot Parser; bulk callers should use the method form to share Tagger compilation across files.

type Tree

type Tree struct {
	Root   *gotreesitter.Node
	Source []byte
	Lang   string
	// contains filtered or unexported fields
}

Tree represents a parsed source file.