cli

package
v0.14.0 Latest Latest
Warning

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

 Go to latest Published: Sep 25, 2026 License: Apache-2.0 Imports: 50 Imported by: 0

Documentation

Overview

Package cli provides the Cobra command tree for the codegraph binary. Each verb lives in its own file; this file contains shared UI helpers.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewRootCmd 

func NewRootCmd() *cobra.Command

NewRootCmd builds and returns the root Cobra command with all sub-commands attached. It does NOT call Execute() — the caller does.

Types

type BriefSymbol added in v0.5.0 

type BriefSymbol struct {
	ID            string         `json:"id"`
	Kind          model.NodeKind `json:"kind"`
	Name          string         `json:"name"`
	QualifiedName string         `json:"qualifiedName"`
	FilePath      string         `json:"filePath"`
	Language      model.Language `json:"language"`
	StartLine     int            `json:"startLine"`
	EndLine       int            `json:"endLine"`
	StartColumn   int            `json:"startColumn"`
	EndColumn     int            `json:"endColumn"`
	Signature     string         `json:"signature,omitempty"`
}

BriefSymbol is the compact, stable discovery shape for automation. It intentionally excludes documentation, decorators, and result scores so an agent can choose a symbol before requesting its source with `node`.

type CalleesResult 

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

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

type CallersResult 

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

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

type ContextCallee added in v0.14.0 

type ContextCallee struct {
	Symbol     BriefSymbol `json:"symbol"`
	Seam       string      `json:"seam,omitempty"`       // interface | field | parameter
	SeamSource string      `json:"seamSource,omitempty"` // graph | inferred; set whenever Seam is non-empty
}

ContextCallee is section (c): a direct callee, signature only.

Seam is "interface" (a real graph fact: an incoming contains edge from a KindInterface owner) or "field"/"parameter" (a best-effort text scan over the caller's own source/signature — see seamKind). SeamSource makes that distinction explicit for consumers: "graph" for interface, "inferred" for field/parameter. It is set whenever Seam is non-empty.

type ContextNotFound added in v0.14.0 

type ContextNotFound struct {
	Requested  string        `json:"requested"`
	Status     string        `json:"status"` // not_found | ambiguous
	Hint       string        `json:"hint,omitempty"`
	Candidates []BriefSymbol `json:"candidates,omitempty"`
}

ContextNotFound reports a requested symbol that did not resolve to exactly one node; it never blocks the other requested symbols.

type ContextResult added in v0.14.0 

type ContextResult struct {
	Requested       []string          `json:"requested"`
	Budget          int               `json:"budget"`
	Unresolved      []ContextNotFound `json:"unresolved,omitempty"`
	Sources         []ContextSource   `json:"sources,omitempty"`
	Types           []ContextType     `json:"types,omitempty"`
	Callees         []ContextCallee   `json:"callees,omitempty"`
	Tests           []ContextTestRef  `json:"tests,omitempty"`
	Helpers         []ContextType     `json:"helpers,omitempty"`
	Omitted         []string          `json:"omitted,omitempty"`
	TokensEstimated int               `json:"tokensEstimated"`
}

ContextResult is the JSON payload for `codegrapher context`.

type ContextSource added in v0.14.0 

type ContextSource struct {
	Symbol    BriefSymbol `json:"symbol"`
	Source    string      `json:"source"`
	Narrowed  bool        `json:"narrowed,omitempty"`
	StartLine int         `json:"startLine,omitempty"`
	EndLine   int         `json:"endLine,omitempty"`
}

ContextSource is section (a): one requested symbol's line-bounded source.

A --line target that falls inside a nested function literal (a closure with no name of its own — an anonymous RunE callback; a switch/loop body has none of these either, but those are not literals) resolves to the innermost NAMED enclosing function/method, per A1 (resolveByFileLine), and Source is that function's WHOLE body, not just the literal: a closure only makes sense read alongside the function that declares the variables it captures and wires it up (founder correction, 2026-09-25 — the earlier design narrowed to the literal's own few lines and lost exactly that context). Every line of a target literal carries a trailing "// TARGET" marker (see A1/resolveClosureNarrowing) so the reader can still find it inside the full function. StartLine/EndLine are always the enclosing node's own declared bounds, even when Narrowed is true.

Narrowed is true only when the enclosing function is longer than --max-function-lines: Source then keeps just the target literal(s) whole, the lines declaring the free variables they capture (go/ast scope), and the statement that registers/calls each literal, joined by explicit "// … N lines elided" markers — never a silent drop.

type ContextTestRef added in v0.14.0 

type ContextTestRef struct {
	Name      string `json:"name"`
	FilePath  string `json:"filePath"`
	StartLine int    `json:"startLine"`
	Hops      int    `json:"hops"` // 1 = direct, 2 = one hop
}

ContextTestRef is section (d): an existing test that calls the symbol.

type ContextType added in v0.14.0 

type ContextType struct {
	Roles          []string    `json:"roles"`
	HeuristicRoles []string    `json:"heuristicRoles,omitempty"` // subset of Roles that are text-scan-derived, not graph-verified
	For            string      `json:"for,omitempty"`            // constructor's target type name
	Symbol         BriefSymbol `json:"symbol"`
	Source         string      `json:"source"`
}

ContextType is section (b)/(e): a full type or constructor declaration.

Roles are a mix of graph-verified facts (receiver, parameter/result, constructor — all real edges/lookups) and, for "field", a best-effort text scan (see fieldReadsOf/parseStructFields) that can miss or misfire on a shadowed receiver name, an unparsed embedded/generic field, etc. HeuristicRoles names the subset of Roles that came from that text scan rather than the graph, so a consumer can tell "the graph says so" from "a regex guessed" instead of trusting every role at the same confidence.

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.

type GraphQuerier 

type GraphQuerier interface {
	// SearchNodes runs the symbol-search pipeline and returns scored results.
	SearchNodes(rawQuery string, opts SearchOptions) ([]model.SearchResult, error)

	// Callers returns the set of symbols that call the given symbol name.
	Callers(symbol string) (*CallersResult, error)

	// Callees returns the set of symbols that the given symbol name calls.
	Callees(symbol string) (*CalleesResult, error)

	// Impact returns the blast-radius for the given symbol name.
	Impact(symbol string, depth int) (*ImpactResult, error)

	// Status returns index statistics.
	Status(projectPath string) (*StatusResult, error)

	// Files returns the list of indexed files.
	Files() ([]FileInfo, error)
}

GraphQuerier is the narrow read-only interface the CLI needs from the query layer. Implement it against the real query package; use mockQuerier in tests.

func NewStoreQuerier 

func NewStoreQuerier(stores ...*store.Store) GraphQuerier

NewStoreQuerier wraps one or more *store.Store as a GraphQuerier. With a single store it behaves identically to the original single-store wrapper.

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"`
	Note      string      `json:"note,omitempty"`
}

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

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 NodeFreshness added in v0.5.0 

type NodeFreshness struct {
	Refreshed bool `json:"refreshed"`
	Verified  bool `json:"verified"`
}

type NodeRelation added in v0.5.0 

type NodeRelation struct {
	Direction  string         `json:"direction"`
	Kind       model.EdgeKind `json:"kind"`
	Symbol     BriefSymbol    `json:"symbol"`
	Provenance string         `json:"provenance,omitempty"`
	Line       int            `json:"line,omitempty"`
	Column     int            `json:"column,omitempty"`
}

type NodeResult added in v0.5.0 

type NodeResult struct {
	Requested   string         `json:"requested"`
	Status      string         `json:"status"`
	Hint        string         `json:"hint,omitempty"`
	Symbol      *BriefSymbol   `json:"symbol,omitempty"`
	Source      string         `json:"source,omitempty"`
	SourceRange string         `json:"sourceRange,omitempty"`
	Freshness   NodeFreshness  `json:"freshness"`
	Relations   []NodeRelation `json:"relations,omitempty"`
	Candidates  []BriefSymbol  `json:"candidates,omitempty"`
}

NodeResult is a symbol-oriented view of an indexed node. Source is omitted from JSON by default; text output renders it as a raw fenced code block.

type PathEdge added in v0.10.0 

type PathEdge struct {
	Kind       model.EdgeKind `json:"kind"`
	Line       int            `json:"line,omitempty"`
	Column     int            `json:"column,omitempty"`
	Provenance string         `json:"provenance,omitempty"`
}

type PathResult added in v0.10.0 

type PathResult struct {
	Start            string        `json:"start"`
	Target           string        `json:"target"`
	Status           string        `json:"status"`
	Hint             string        `json:"hint,omitempty"`
	Freshness        NodeFreshness `json:"freshness"`
	MaxHops          int           `json:"maxHops"`
	MaxNodes         int           `json:"maxNodes"`
	MaxEdges         int           `json:"maxEdges"`
	VisitedNodes     int           `json:"visitedNodes"`
	VisitedEdges     int           `json:"visitedEdges"`
	Truncated        bool          `json:"truncated,omitempty"`
	Steps            []PathStep    `json:"steps,omitempty"`
	StartCandidates  []BriefSymbol `json:"startCandidates,omitempty"`
	TargetCandidates []BriefSymbol `json:"targetCandidates,omitempty"`
}

PathResult is one bounded, directed call path. A path is static graph evidence: it describes one possible route, not an observed execution.

type PathStep added in v0.10.0 

type PathStep struct {
	Symbol BriefSymbol `json:"symbol"`
	Edge   *PathEdge   `json:"edge,omitempty"`
	Source string      `json:"source,omitempty"`
}

PathStep is a symbol on a path. Edge describes the transition from the preceding step; it is omitted for the starting symbol.

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.

type StackTraceFrame added in v0.10.0 

type StackTraceFrame struct {
	Index          int           `json:"index"`
	Raw            string        `json:"raw"`
	Function       string        `json:"function,omitempty"`
	FilePath       string        `json:"filePath,omitempty"`
	Line           int           `json:"line,omitempty"`
	Column         int           `json:"column,omitempty"`
	Status         string        `json:"status"`
	Hint           string        `json:"hint,omitempty"`
	Symbol         *BriefSymbol  `json:"symbol,omitempty"`
	Candidates     []BriefSymbol `json:"candidates,omitempty"`
	PathCandidates []string      `json:"pathCandidates,omitempty"`
	Source         string        `json:"source,omitempty"`
}

type StackTraceResult added in v0.10.0 

type StackTraceResult struct {
	Status    string            `json:"status"`
	Hint      string            `json:"hint,omitempty"`
	Freshness NodeFreshness     `json:"freshness"`
	Revision  string            `json:"revision,omitempty"`
	MaxFrames int               `json:"maxFrames"`
	Truncated bool              `json:"truncated,omitempty"`
	Frames    []StackTraceFrame `json:"frames"`
}

StackTraceResult maps runtime frames to the current, freshly-indexed source. It intentionally does not infer edges between frames: a stack is runtime evidence and may cross reflection, generated code, or framework callbacks.

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 `codegrapher status`.

type StoreQuerier 

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

StoreQuerier implements GraphQuerier by fanning each operation out across a slice of per-scope stores and merging the results in Go. The data model is one SQLite DB per (language, version) scope; every underlying query func is single-scope, so whole-repo answers come from running each query per store and merging — mirroring mcp.MultiBackend.

For a single store, every method delegates to behavior byte-identical to the previous single-store StoreQuerier.

Tests use mockQuerier instead.

func (*StoreQuerier) Callees 

func (q *StoreQuerier) Callees(symbol string) (*CalleesResult, error)

func (*StoreQuerier) Callers 

func (q *StoreQuerier) Callers(symbol string) (*CallersResult, error)

func (*StoreQuerier) Files 

func (q *StoreQuerier) Files() ([]FileInfo, error)

func (*StoreQuerier) Impact 

func (q *StoreQuerier) Impact(symbol string, depth int) (*ImpactResult, error)

func (*StoreQuerier) SearchNodes 

func (q *StoreQuerier) SearchNodes(rawQuery string, opts SearchOptions) ([]model.SearchResult, error)

func (*StoreQuerier) Status 

func (q *StoreQuerier) Status(projectPath string) (*StatusResult, error)

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. Matches the `callers`/`callees` array element shape in the golden JSON.

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.