query

Documentation

Overview

Package query implements the QUERY layer: symbol search, graph traversal (callers/callees/impact), and index status/files verbs.

Ported from src/db/queries.ts, src/graph/traversal.ts, src/search/query-parser.ts, src/search/query-utils.ts, and src/bin/codegraph.ts of github.com/colbymchenry/codegraph (MIT).

Public functions accept a *store.Store and return typed structs that marshal to the exact JSON payloads produced by the original CLI's --json flags.

Index

• func BoundedEditDistance(a, b string, maxDist int) int
• func HasExactMatch(s *store.Store, symbol string) (bool, error)
• func IsGeneratedFile(filePath string) bool
• func IsTestFile(filePath string) bool
• func KindBonus(kind model.NodeKind) float64
• func NameMatchBonus(nodeName, query string) float64
• func ScorePathRelevance(filePath, query string, projectNameTokens map[string]struct{}) float64
• func SearchNodes(s *store.Store, rawQuery string, opts SearchOptions) ([]model.SearchResult, error)
• type CalleesResult
  • func Callees(s *store.Store, symbol string) (*CalleesResult, error)
• type CallersResult
  • func Callers(s *store.Store, symbol string) (*CallersResult, error)
• type FileInfo
  • func Files(s *store.Store) ([]FileInfo, error)
• type ImpactResult
  • func Impact(s *store.Store, symbol string, depth int) (*ImpactResult, error)
• type IndexInfo
• type ParsedQuery
  • func ParseQuery(raw string) ParsedQuery
• type PendingChanges
• type SearchOptions
• type StatusResult
  • func Status(s *store.Store, projectPath string) (*StatusResult, error)
• type SymbolRef

Functions

func BoundedEditDistance

func BoundedEditDistance(a, b string, maxDist int) int

BoundedEditDistance computes a bounded Levenshtein distance between a and b. Returns maxDist+1 as soon as distance exceeds maxDist. Mirrors boundedEditDistance from src/search/query-parser.ts.

func HasExactMatch

func HasExactMatch(s *store.Store, symbol string) (bool, error)

HasExactMatch reports whether s contains a symbol whose name exactly matches the query (the whole name, or a `.`/`::`-qualified suffix), as opposed to only a fuzzy/substring search hit. Multi-store callers use this to prefer exact-match scopes, so a verb like callers/callees/impact does not leak a substring hit from a scope where the symbol appears only as a substring (e.g. "get" matching "Widget").

func IsGeneratedFile

func IsGeneratedFile(filePath string) bool

IsGeneratedFile returns true for files that appear auto-generated. Mirrors isGeneratedFile from src/extraction/generated-detection.ts.

func IsTestFile

func IsTestFile(filePath string) bool

IsTestFile checks whether a file path looks like a test file. Mirrors isTestFile from src/search/query-utils.ts.

func KindBonus

func KindBonus(kind model.NodeKind) float64

KindBonus returns the relevance bonus for a node kind. Mirrors kindBonus from src/search/query-utils.ts.

func NameMatchBonus

func NameMatchBonus(nodeName, query string) float64

NameMatchBonus returns a score bonus when the node name matches the query. Mirrors nameMatchBonus from src/search/query-utils.ts.

func ScorePathRelevance

func ScorePathRelevance(filePath, query string, projectNameTokens map[string]struct{}) float64

ScorePathRelevance returns a relevance score for a file path against a query. Mirrors scorePathRelevance from src/search/query-utils.ts. projectNameTokens can be nil (no down-weighting).

func SearchNodes

func SearchNodes(s *store.Store, rawQuery string, opts SearchOptions) ([]model.SearchResult, error)

SearchNodes runs the multi-strategy search pipeline (FTS5 → LIKE → fuzzy, with exact-name supplement and multi-signal rescoring). Mirrors QueryBuilder.searchNodes from src/db/queries.ts.

Types

type CalleesResult

type CalleesResult struct {
	Symbol  string      `json:"symbol"`
	Callees []SymbolRef `json:"callees"`
}

CalleesResult is the JSON payload for `codegraph callees <symbol>`.

func Callees

func Callees(s *store.Store, symbol string) (*CalleesResult, error)

Callees returns the set of nodes called by any definition matching symbol.

type CallersResult

type CallersResult struct {
	Symbol  string      `json:"symbol"`
	Callers []SymbolRef `json:"callers"`
}

CallersResult is the JSON payload for `codegraph callers <symbol>`.

func Callers

func Callers(s *store.Store, symbol string) (*CallersResult, error)

Callers returns the set of nodes that call any definition matching symbol. Mirrors the callers verb assembly in src/bin/codegraph.ts.

type FileInfo

type FileInfo struct {
	Path      string         `json:"path"`
	Language  model.Language `json:"language"`
	NodeCount int            `json:"nodeCount"`
	Size      int64          `json:"size"`
}

FileInfo is one entry in the `files` JSON array.

func Files

func Files(s *store.Store) ([]FileInfo, error)

Files returns the files verb payload: path, language, nodeCount, size for every tracked file, sorted by path.

type ImpactResult

type ImpactResult struct {
	Symbol    string      `json:"symbol"`
	Depth     int         `json:"depth"`
	NodeCount int         `json:"nodeCount"`
	EdgeCount int         `json:"edgeCount"`
	Affected  []SymbolRef `json:"affected"`
}

ImpactResult is the JSON payload for `codegraph impact <symbol>`.

func Impact

func Impact(s *store.Store, symbol string, depth int) (*ImpactResult, error)

Impact returns the blast-radius subgraph for any definition matching symbol. Mirrors the impact verb assembly in src/bin/codegraph.ts.

type IndexInfo

type IndexInfo struct {
	BuiltWithVersion           string `json:"builtWithVersion"`
	BuiltWithExtractionVersion int    `json:"builtWithExtractionVersion"`
	CurrentExtractionVersion   int    `json:"currentExtractionVersion"`
	ReindexRecommended         bool   `json:"reindexRecommended"`
}

IndexInfo mirrors the `index` block of the status payload.

type ParsedQuery

type ParsedQuery struct {
	// Free-text portion to feed to FTS / LIKE. May be empty.
	Text string
	// kind: filters (OR'd). Empty when none specified.
	Kinds []model.NodeKind
	// lang:/language: filters (OR'd). Empty when none specified.
	Languages []model.Language
	// path: filters (OR'd, case-insensitive substring of file_path).
	PathFilters []string
	// name: filters (OR'd, case-insensitive substring of node.name).
	NameFilters []string
}

ParsedQuery holds the result of parsing a raw search string. Mirrors ParsedQuery from src/search/query-parser.ts.

func ParseQuery

func ParseQuery(raw string) ParsedQuery

ParseQuery parses a raw query string into structured filters + remaining text. Mirrors parseQuery from src/search/query-parser.ts. Always returns a value; never panics.

type PendingChanges

type PendingChanges struct {
	Added    int `json:"added"`
	Modified int `json:"modified"`
	Removed  int `json:"removed"`
}

PendingChanges mirrors the pendingChanges field in the status payload.

type SearchOptions

type SearchOptions struct {
	Limit     int
	Offset    int
	Kinds     []model.NodeKind
	Languages []model.Language
}

SearchOptions controls result set size and filtering for SearchNodes.

type StatusResult

type StatusResult struct {
	Initialized      bool                   `json:"initialized"`
	Version          string                 `json:"version"`
	ProjectPath      string                 `json:"projectPath"`
	IndexPath        string                 `json:"indexPath"`
	LastIndexed      string                 `json:"lastIndexed"`
	FileCount        int                    `json:"fileCount"`
	NodeCount        int                    `json:"nodeCount"`
	EdgeCount        int                    `json:"edgeCount"`
	DBSizeBytes      int64                  `json:"dbSizeBytes"`
	Backend          string                 `json:"backend"`
	JournalMode      string                 `json:"journalMode"`
	NodesByKind      map[model.NodeKind]int `json:"nodesByKind"`
	Languages        []string               `json:"languages"`
	PendingChanges   PendingChanges         `json:"pendingChanges"`
	WorktreeMismatch any                    `json:"worktreeMismatch"`
	Index            IndexInfo              `json:"index"`
}

StatusResult is the JSON payload for `codegraph status`.

func Status

func Status(s *store.Store, projectPath string) (*StatusResult, error)

Status assembles the status payload for a store. projectPath is the project root directory (for the projectPath field).

type SymbolRef

type SymbolRef struct {
	Name      string         `json:"name"`
	Kind      model.NodeKind `json:"kind"`
	FilePath  string         `json:"filePath"`
	StartLine int            `json:"startLine"`
}

SymbolRef is the shape used in callers/callees/affected arrays.