astkit

type CallSite struct {
	Callee string `json:"callee"`
	Line   int    `json:"line"`
	// Write marks an attribute site used as an assignment target. It is false
	// for calls and ordinary reads, preserving older serialized indexes.
	Write bool `json:"write,omitempty"`
	// ReferenceOnly marks a callable reference that does not execute at this
	// location (Java Foo::bar, Go T.Method). Consumers may use it for rename
	// and reference analysis but must not turn it into a calls edge.
	ReferenceOnly bool `json:"reference_only,omitempty"`
	// Argc is the number of argument expressions at the call site (0 may
	// mean "no arguments" or "unknown" for older indexes; consumers treat
	// it as advisory). Lets graph consumers disambiguate overloads.
	Argc int `json:"argc,omitempty"`
	// Args holds each argument's identifier when the argument is a bare
	// identifier, "" otherwise. With local type inference downstream, this
	// disambiguates same-arity overloads (isEmpty(char[]) vs isEmpty(long[])).
	Args []string `json:"args,omitempty"`
	// Generic reports whether the call carries explicit type arguments
	// (C# DeserializeObject<T>(...), the turbofish/`<...>` form). Lets graph
	// consumers split a generic overload from its same-arity non-generic
	// sibling, which bare-name + argc + value-arg types cannot distinguish.
	Generic bool `json:"generic,omitempty"`
}

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

type Export struct {
	Name string     `json:"name"`
	Kind SymbolKind `json:"kind"`
}

type ImportStatement struct {
	// Raw is the original source text of the clause.
	Raw string `json:"raw"`

	// Path is the imported module/package path.
	Path string `json:"path"`

	// Alias is the local binding name, if the import was aliased.
	Alias string `json:"alias,omitempty"`

	// Names lists the members a from-import binds ("from . import cli, app"
	// → ["cli", "app"]). A member may itself be a submodule; consumers that
	// resolve module paths decide which. Empty for whole-module imports.
	Names []string `json:"names,omitempty"`

	// Group classifies the import as stdlib | external | relative when known.
	Group string `json:"group,omitempty"`

	// Line is the 1-indexed source line of the clause.
	Line int `json:"line"`
}

type LanguageKey string

type LineRange struct {
	Start int `json:"start"`
	End   int `json:"end"`
}

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

type Strategy interface {
	Language() LanguageKey
	Extensions() []string
	Extract(tree *sitter.Tree, src []byte) ([]Symbol, error)
	ExtractImports(tree *sitter.Tree, src []byte) ([]ImportStatement, error)
}

type Symbol struct {
	// Kind classifies the declaration (function, class, etc.).
	Kind SymbolKind `json:"kind"`

	// Name is the bare identifier (e.g. "Bar" for method Foo.Bar).
	Name string `json:"name"`

	// QualifiedName disambiguates within a file (e.g. "Foo.Bar" for methods
	// of class Foo). For top-level symbols it equals Name.
	QualifiedName string `json:"qualifiedName"`

	// ParentName is the immediate enclosing type/class name, if any.
	ParentName string `json:"parentName,omitempty"`

	// Signature is the declaration text without a body (best-effort).
	Signature string `json:"signature"`

	// Docstring is the language-idiomatic documentation comment immediately
	// preceding the declaration, if any. Producers MAY leave this empty and
	// let downstream consumers attach it from raw source.
	Docstring string `json:"docstring,omitempty"`

	// Body is the full source text covering the declaration including its
	// body. Required by consumers that need to reconstruct merged source
	// (Fuse). Grove may drop this before persisting.
	Body string `json:"body,omitempty"`

	// Span is the 1-indexed inclusive line range covered by Body.
	Span LineRange `json:"span"`

	// Exported reports whether the declaration is visible outside its
	// defining unit (file/module/package), per language semantics.
	Exported bool `json:"exported"`

	// Modifiers lists language-idiomatic modifier keywords (public, static,
	// async, pub, etc.).
	Modifiers []string `json:"modifiers,omitempty"`

	// TypeParameters lists generic type parameters declared on the symbol
	// (e.g. ["T", "U"] for `func F[T any, U Comparable]`).
	TypeParameters []string `json:"typeParameters,omitempty"`

	// Annotations lists raw annotation/decorator/attribute text attached to
	// the symbol (Java @Override, Rust #[derive(...)], Python @cache, …).
	Annotations []string `json:"annotations,omitempty"`

	// CallSites records every call expression observed inside Body, when the
	// strategy supports call-site extraction.
	CallSites []CallSite `json:"callSites,omitempty"`

	// AttrSites records attribute accesses that are NOT call expressions
	// ("x.blueprints" with no parens). Python-only today: these are how
	// @property code executes, so graph consumers need them to model
	// property calls. Same shape as CallSites ("qualifier.name").
	AttrSites []CallSite `json:"attrSites,omitempty"`
}

type SymbolKind string

type TextStrategy interface {
	Strategy
	// ExtractsFromText reports that Extract tolerates a nil tree.
	ExtractsFromText() bool
}