Help us shape the future of Go! Take the 2026 Go Developer Survey

query

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 18, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package query implements graphmaster's code-graph tools (PLAN "MCP tool'ları") as a plain Go API, independent of MCP: find_symbol, search, repo_map, file_outline, read_symbol, callers, callees, impact, imports, inheritance, tests_for, traverse and status.

Every tool follows one output contract:

  • the index is freshened first (Engine's Freshener) and the first line is the banner "graphmaster <tool> · <freshness>";
  • the answer is plain text bounded by max_tokens (default 1500, cap 6000, estimated as bytes/4);
  • symbols render as "<kind> <qname> <path>:<start>-<end> <sig>", the qname without prefixes the path already implies (sym.displayQName: "steer.F" for a Go import path, "User.role" for a TS file module);
  • cut lists end with "… +N more (narrow path_prefix / raise limit)";
  • edges below confidence 80 are marked with "~".

Symbol arguments accept a qualified name (or a dotted suffix of one), path:line, a bare name or a 16-digit skey; an ambiguous argument yields a numbered candidate list instead of an answer.

The MCP server and the `graphmaster query` CLI both drive the tools through Tools, so they print identical text.

Index

Constants

View Source 
const (
	DefaultMaxTokens = 1500
	MaxTokensCap     = 6000
)

Token budget (PLAN "MCP tool'ları"): output size is bounded by max_tokens, estimated as bytes/4.

View Source 
const DefaultFreshenBudget = 20 * time.Second

DefaultFreshenBudget is how long a tool call waits for the write lock before answering from the current graph (PLAN: MCP 20s).

Variables

View Source 
var ErrInvalidArgument = errors.New("invalid argument")

ErrInvalidArgument marks errors caused by tool arguments rather than the index; callers can show them to the agent as a usage error.

Functions

This section is empty.

Types

type Backend 

type Backend interface {
	// Store returns the current graph.db (it may change after Freshen).
	Store() *store.Store
	// Root locates the working tree (for reading sources and git state).
	Root() *repo.Root
	// Status summarizes the index for the status tool.
	Status(ctx context.Context) (*index.Status, error)
}

Backend gives the tools access to the index. *index.Indexer implements it.

type CallsInput 

type CallsInput struct {
	Symbol        string `json:"symbol" jsonschema:"qname, path:line, bare name or skey"`
	Depth         int    `json:"depth,omitempty" jsonschema:"levels to follow (default 1, max 5)"`
	MinConfidence int    `json:"min_confidence,omitempty" jsonschema:"minimum edge confidence 1-100 (default 50)"`
	Limit         int    `json:"limit,omitempty" jsonschema:"maximum symbols (default 50)"`
	MaxTokens     int    `json:"max_tokens,omitempty" jsonschema:"output budget in tokens (default 1500, max 6000)"`
}

CallsInput are the callers and callees arguments.

type Engine 

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

Engine runs the query tools against one repository. Apart from a cache of the files table (invalidated by files_gen) it holds no state; it is safe for concurrent use.

func New 

func New(b Backend, opts Options) *Engine

New returns an Engine over b.

func (*Engine) Callees 

func (e *Engine) Callees(ctx context.Context, in CallsInput) (string, error)

Callees prints the tree of definitions symbol calls.

func (*Engine) Callers 

func (e *Engine) Callers(ctx context.Context, in CallsInput) (string, error)

Callers prints the tree of definitions calling symbol.

func (*Engine) FileOutline 

func (e *Engine) FileOutline(ctx context.Context, in FileOutlineInput) (string, error)

FileOutline lists a file's definitions as a tree with line ranges and signatures.

func (*Engine) FindSymbol 

func (e *Engine) FindSymbol(ctx context.Context, in FindSymbolInput) (string, error)

FindSymbol lists definitions by name: exact matches first, then prefix and fuzzy matches, exported definitions before private ones.

func (*Engine) Impact 

func (e *Engine) Impact(ctx context.Context, in ImpactInput) (string, error)

Impact lists what may break when a symbol, a file or the uncommitted changes are modified: the reverse transitive closure over dependency edges, grouped by file, with the number of affected tests.

func (*Engine) Imports 

func (e *Engine) Imports(ctx context.Context, in ImportsInput) (string, error)

Imports lists what a file or package imports (direction=out) or who imports it (direction=in).

func (*Engine) Inheritance 

func (e *Engine) Inheritance(ctx context.Context, in InheritanceInput) (string, error)

Inheritance prints the type hierarchy around a type: supertypes (up), subtypes (down) or both.

func (*Engine) ReadSymbol 

func (e *Engine) ReadSymbol(ctx context.Context, in ReadSymbolInput) (string, error)

ReadSymbol prints a definition's header row followed by its numbered source lines (plus optional context), read from the working tree.

func (*Engine) RepoMap 

func (e *Engine) RepoMap(ctx context.Context, in RepoMapInput) (string, error)

RepoMap renders the directory / package tree below path_prefix with file counts, lines of code and the three most referenced exported top-level definitions of each directory (tests excluded). A directory whose subdirectories are listed shows only the symbols of its own files, so the same names are not repeated on every ancestor row.

func (*Engine) Search 

func (e *Engine) Search(ctx context.Context, in SearchInput) (string, error)

Search runs a full-text (token prefix) and trigram (substring) search over symbol names, plus a substring match over file paths.

func (*Engine) Status 

func (e *Engine) Status(ctx context.Context, in StatusInput) (string, error)

Status reports file states, languages, database size, last scan and the steering mode.

func (*Engine) TestsFor 

func (e *Engine) TestsFor(ctx context.Context, in TestsForInput) (string, error)

TestsFor lists test functions that reach a symbol within two hops of calls / test edges, plus tests whose name contains the symbol's name.

func (*Engine) Traverse 

func (e *Engine) Traverse(ctx context.Context, in TraverseInput) (string, error)

Traverse explores the graph around a symbol breadth-first in Go: one batched IN query per level, neighbors ranked by confidence × 1/degree so specific links win over hubs, and hubs summarized instead of expanded.

type FileOutlineInput 

type FileOutlineInput struct {
	Path           string `json:"path" jsonschema:"repo-relative file path"`
	Depth          int    `json:"depth,omitempty" jsonschema:"nesting levels to show (default 2)"`
	IncludePrivate *bool  `json:"include_private,omitempty" jsonschema:"include non-exported definitions (default true)"`
	MaxTokens      int    `json:"max_tokens,omitempty" jsonschema:"output budget in tokens (default 1500, max 6000)"`
}

FileOutlineInput are the file_outline arguments.

type FindSymbolInput 

type FindSymbolInput struct {
	Query      string `json:"query" jsonschema:"symbol name, qualified name, prefix or substring"`
	Kind       string `json:"kind,omitempty" jsonschema:"only this definition kind (function, method, class, struct, interface, ...)"`
	Lang       string `json:"lang,omitempty" jsonschema:"only this language (go, python, typescript, ...)"`
	PathPrefix string `json:"path_prefix,omitempty" jsonschema:"only files whose repo-relative path starts with this"`
	Exact      bool   `json:"exact,omitempty" jsonschema:"exact name match only"`
	Limit      int    `json:"limit,omitempty" jsonschema:"maximum results (default 20)"`
	MaxTokens  int    `json:"max_tokens,omitempty" jsonschema:"output budget in tokens (default 1500, max 6000)"`
}

FindSymbolInput are the find_symbol arguments.

type Freshener 

type Freshener interface {
	Freshen(ctx context.Context, budget time.Duration) (*index.Result, error)
}

Freshener brings the index up to date before a tool answers. *index.Indexer implements it; tests inject a fixed result.

type ImpactInput 

type ImpactInput struct {
	Symbol        string `json:"symbol,omitempty" jsonschema:"qname, path:line, bare name or skey"`
	Path          string `json:"path,omitempty" jsonschema:"repo-relative file path"`
	Changed       bool   `json:"changed,omitempty" jsonschema:"start from files changed against HEAD / the git index"`
	Depth         int    `json:"depth,omitempty" jsonschema:"levels to follow (default 3, max 6)"`
	MinConfidence int    `json:"min_confidence,omitempty" jsonschema:"minimum edge confidence 1-100 (default 30)"`
	MaxTokens     int    `json:"max_tokens,omitempty" jsonschema:"output budget in tokens (default 1500, max 6000)"`
}

ImpactInput are the impact arguments; exactly one of Symbol, Path and Changed selects the starting set.

type ImportsInput 

type ImportsInput struct {
	Path      string `json:"path,omitempty" jsonschema:"repo-relative file path (or package directory)"`
	Module    string `json:"module,omitempty" jsonschema:"package / module name or import spec"`
	Direction string `json:"direction,omitempty" jsonschema:"out (what it imports, default) or in (who imports it)"`
	MaxTokens int    `json:"max_tokens,omitempty" jsonschema:"output budget in tokens (default 1500, max 6000)"`
}

ImportsInput are the imports arguments.

type InheritanceInput 

type InheritanceInput struct {
	Symbol    string `json:"symbol" jsonschema:"qname, path:line, bare name or skey of a type"`
	Direction string `json:"direction,omitempty" jsonschema:"up (supertypes), down (subtypes) or both (default)"`
	Depth     int    `json:"depth,omitempty" jsonschema:"levels to follow (default 3)"`
	MaxTokens int    `json:"max_tokens,omitempty" jsonschema:"output budget in tokens (default 1500, max 6000)"`
}

InheritanceInput are the inheritance arguments.

type Options 

type Options struct {
	// Freshener runs before every tool. Nil uses the backend when it
	// implements Freshener, otherwise tools answer without freshening.
	Freshener Freshener
	// FreshenBudget bounds the wait for the write lock (default: the
	// backend's timeouts.mcp when it exposes its config, else 20s).
	FreshenBudget time.Duration
	// NoGit reports that the backend indexes a directory outside git, so
	// impact changed=true has nothing to compare against.
	NoGit bool
}

Options configure an Engine.

type ReadSymbolInput 

type ReadSymbolInput struct {
	Symbol       string `json:"symbol" jsonschema:"qname, path:line, bare name or skey"`
	ContextLines int    `json:"context_lines,omitempty" jsonschema:"extra lines before and after (default 0)"`
	MaxLines     int    `json:"max_lines,omitempty" jsonschema:"maximum source lines (default 200)"`
	MaxTokens    int    `json:"max_tokens,omitempty" jsonschema:"output budget in tokens (default 1500, max 6000)"`
}

ReadSymbolInput are the read_symbol arguments.

type RepoMapInput 

type RepoMapInput struct {
	PathPrefix string `json:"path_prefix,omitempty" jsonschema:"directory to map (default: repository root)"`
	Depth      int    `json:"depth,omitempty" jsonschema:"directory levels to show (default 2)"`
	MaxTokens  int    `json:"max_tokens,omitempty" jsonschema:"output budget in tokens (default 1500, max 6000)"`
}

RepoMapInput are the repo_map arguments.

type SearchInput 

type SearchInput struct {
	Query      string   `json:"query" jsonschema:"words or identifier fragments to search in symbol and file names"`
	Kinds      []string `json:"kinds,omitempty" jsonschema:"restrict to these definition kinds; include \"file\" for file names"`
	PathPrefix string   `json:"path_prefix,omitempty" jsonschema:"only files whose repo-relative path starts with this"`
	Limit      int      `json:"limit,omitempty" jsonschema:"maximum results (default 30)"`
	MaxTokens  int      `json:"max_tokens,omitempty" jsonschema:"output budget in tokens (default 1500, max 6000)"`
}

SearchInput are the search arguments.

type StatusInput 

type StatusInput struct {
	MaxTokens int `json:"max_tokens,omitempty" jsonschema:"output budget in tokens (default 1500, max 6000)"`
}

StatusInput are the status arguments.

type TestsForInput 

type TestsForInput struct {
	Symbol    string `json:"symbol" jsonschema:"qname, path:line, bare name or skey"`
	MaxTokens int    `json:"max_tokens,omitempty" jsonschema:"output budget in tokens (default 1500, max 6000)"`
}

TestsForInput are the tests_for arguments.

type Tool 

type Tool struct {
	// Name is the MCP tool name, e.g. "find_symbol".
	Name string
	// Description is shown to agents and in CLI help.
	Description string
	// Primary is the json name of the argument the CLI takes positionally
	// ("" when the tool has none).
	Primary string
	// NewInput returns a pointer to a zero input struct (e.g.
	// *FindSymbolInput) to decode arguments into.
	NewInput func() any
	// Run executes the tool with an input created by NewInput.
	Run func(ctx context.Context, e *Engine, in any) (string, error)
}

Tool describes one query tool for the MCP server and the CLI.

func Lookup 

func Lookup(name string) (Tool, bool)

Lookup returns the tool with the given name.

func Tools 

func Tools() []Tool

Tools returns every query tool in a stable order.

func (Tool) RunJSON 

func (t Tool) RunJSON(ctx context.Context, e *Engine, args []byte) (string, error)

RunJSON decodes JSON arguments into the tool's input and runs it.

type TraverseInput 

type TraverseInput struct {
	Start         string   `json:"start" jsonschema:"qname, path:line, bare name or skey"`
	EdgeKinds     []string `` /* 136-byte string literal not displayed */
	Direction     string   `json:"direction,omitempty" jsonschema:"out (default), in or both"`
	MaxDepth      int      `json:"max_depth,omitempty" jsonschema:"levels to follow (default 4, max 8)"`
	MinConfidence int      `json:"min_confidence,omitempty" jsonschema:"minimum edge confidence 1-100 (default 50)"`
	MaxTokens     int      `json:"max_tokens,omitempty" jsonschema:"output budget in tokens (default 1500, max 6000)"`
}

TraverseInput are the traverse arguments.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.