symbols

Documentation

Overview

Package symbols extracts declarations and references from source files for richer review context. It is language-pluggable: a registry maps file extensions to Extractor implementations, with a regex fallback for unknown languages.

Index

• func Language(path string) string
• type Extractor
• type GoASTExtractor
  • func (GoASTExtractor) Extract(_ context.Context, path string, src []byte) ([]Symbol, error)
• type GrammarExtractor
  • func NewGrammarExtractor(pool *grammar.Pool) *GrammarExtractor
  • func (e *GrammarExtractor) Extract(ctx context.Context, path string, src []byte) ([]Symbol, error)
• type Kind
• type RegexExtractor
  • func (RegexExtractor) Extract(_ context.Context, path string, src []byte) ([]Symbol, error)
• type Registry
  • func Default() Registry
  • func DefaultWithGrammar(pool *grammar.Pool) Registry
  • func (r Registry) Extract(ctx context.Context, path string, src []byte) ([]Symbol, error)
• type Symbol

Functions

func Language

func Language(path string) string

Language returns a display name for a file extension.

Types

type Extractor

type Extractor interface {
	Extract(ctx context.Context, path string, src []byte) ([]Symbol, error)
}

Extractor pulls symbols out of a single source file.

type GoASTExtractor

type GoASTExtractor struct{}

GoASTExtractor uses the stdlib go/parser and go/ast to extract Go symbols. It is the high-quality extractor for Go files and does not depend on any external grammar or WASM runtime.

func (GoASTExtractor) Extract

func (GoASTExtractor) Extract(_ context.Context, path string, src []byte) ([]Symbol, error)

Extract parses src and returns top-level declarations plus imports.

type GrammarExtractor

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

GrammarExtractor uses a wazero tree-sitter parser pool for C/C++ symbol extraction. It is the Stage 8 proof-of-concept for grammar-backed context beyond what regex or stdlib AST can offer.

func NewGrammarExtractor

func NewGrammarExtractor(pool *grammar.Pool) *GrammarExtractor

NewGrammarExtractor creates an extractor backed by pool.

func (*GrammarExtractor) Extract

func (e *GrammarExtractor) Extract(ctx context.Context, path string, src []byte) ([]Symbol, error)

Extract implements Extractor for C and C++ source files.

type Kind

type Kind string

Kind classifies a symbol.

const (
	KindFunc    Kind = "func"
	KindMethod  Kind = "method"
	KindType    Kind = "type"
	KindVar     Kind = "var"
	KindConst   Kind = "const"
	KindImport  Kind = "import"
	KindField   Kind = "field"
	KindPackage Kind = "package"
	KindUnknown Kind = "unknown"
)

Symbol kinds.

type RegexExtractor

type RegexExtractor struct{}

RegexExtractor is a language-agnostic fallback that uses simple heuristics to pull function, class, and method names. It is intentionally low-fidelity: it never fails and gives the model *some* named anchors even for unsupported languages.

func (RegexExtractor) Extract

func (RegexExtractor) Extract(_ context.Context, path string, src []byte) ([]Symbol, error)

Extract runs regexes over src and returns discovered symbols.

type Registry

type Registry map[string]Extractor

Registry maps file extensions to extractors. The zero value is usable and falls back to the regex extractor for every language.

func Default

func Default() Registry

Default returns a registry with Go handled by the stdlib go/ast extractor and everything else by the regex fallback.

func DefaultWithGrammar

func DefaultWithGrammar(pool *grammar.Pool) Registry

DefaultWithGrammar returns a registry that uses the grammar-backed tree-sitter extractor for C/C++ files and the same extractors as Default for everything else. Callers must supply a parser pool initialised for the languages they want to enable.

func (Registry) Extract

func (r Registry) Extract(ctx context.Context, path string, src []byte) ([]Symbol, error)

Extract picks the extractor by extension and runs it. Unsupported extensions fall back to the regex extractor so every file gets at least token-level names.

type Symbol

type Symbol struct {
	Name      string `json:"name"`
	Kind      Kind   `json:"kind"`
	Path      string `json:"path"`
	Line      int    `json:"line"`
	Signature string `json:"signature,omitempty"`
	Doc       string `json:"doc,omitempty"`
	Receiver  string `json:"receiver,omitempty"`
	Container string `json:"container,omitempty"`
}

Symbol is one extracted declaration or reference.