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

query

package
v0.2.2 Latest Latest
Warning

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

 Go to latest Published: Oct 2, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DefaultCatalogLimit bounds a catalog response when the caller does not
	// ask for a specific bound.
	DefaultCatalogLimit = 100
	// MaxCatalogLimit is the largest bound a caller may request. A catalog
	// that reaches it reports truncation instead of streaming without bounds.
	MaxCatalogLimit = 1000
)
View Source 
const (
	DefaultTestCoverageDepth = 8
	DefaultTestCoverageLimit = 100
	MaxTestCoverageDepth     = 32
	MaxTestCoverageLimit     = 1000
)

Variables

View Source 
var ErrNotFound = errors.New("node not found")

Functions

func DownstreamRelations 

func DownstreamRelations() []graph.EdgeKind

DownstreamRelations returns the relations traversed outgoing from the root to find what the root itself depends on. It mirrors UpstreamRelations; see impactRelations for why the two sets are identical.

func NormalizePathPrefixes 

func NormalizePathPrefixes(values []string) ([]string, error)

NormalizePathPrefixes validates, deduplicates, and orders repository-relative segment prefixes for CLI, MCP, and query callers.

func RenderMermaid 

func RenderMermaid(topology ServiceTopology) string

RenderMermaid renders a stable presentation of structured topology. The generated identifiers never contain graph data, and every label escapes Mermaid control syntax.

func UpstreamRelations 

func UpstreamRelations() []graph.EdgeKind

UpstreamRelations returns the relations traversed incoming from the root to find code that depends on it. Callers must not mutate the result.

Types

type AmbiguousError 

type AmbiguousError struct {
	Term       string               `json:"term"`
	Kind       graph.NodeKind       `json:"kind,omitempty"`
	Level      graph.NodeMatchLevel `json:"level,omitempty"`
	Reason     string               `json:"reason,omitempty"`
	Total      int                  `json:"total"`
	Candidates []graph.Node         `json:"candidates"`
}

AmbiguousError reports that a selector matched several equally good nodes. Total is the number of matches in the graph, which can exceed the number of listed Candidates, so a caller can always tell that the list is partial. Level and Reason say why the candidates were grouped together: they all matched the selector the same way, and no weaker match is ever mixed in.

func (*AmbiguousError) Error 

func (e *AmbiguousError) Error() string

type BoundaryStatus 

type BoundaryStatus string

BoundaryStatus describes how confidently graph evidence crosses a service boundary. Missing means the declaration has no handler edge; unresolved means the edge still targets an external node; ambiguous means several exact graph candidates exist and none was selected. 

const (
	BoundaryResolved   BoundaryStatus = "resolved"
	BoundaryUnresolved BoundaryStatus = "unresolved"
	BoundaryAmbiguous  BoundaryStatus = "ambiguous"
	BoundaryMissing    BoundaryStatus = "missing"
)

type Catalog 

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

Catalog answers read-only inventory and usage questions about data resources, configuration keys, and events. Classification lives here so storage adapters only enumerate.

func NewCatalog 

func NewCatalog(repository graph.CatalogRepository) *Catalog

func (*Catalog) ConfigKeys 

func (c *Catalog) ConfigKeys(ctx context.Context, options CatalogOptions) (ConfigKeyList, error)

ConfigKeys catalogs configuration keys with their definitions and readers. Stored values never appear in the response.

func (*Catalog) DataResourceUsage 

func (c *Catalog) DataResourceUsage(ctx context.Context, selector string, options CatalogOptions) (DataResourceUsage, error)

DataResourceUsage reports the readers and writers of one data resource. An ambiguous name returns candidates instead of guessing one of them.

func (*Catalog) DataResources 

func (c *Catalog) DataResources(ctx context.Context, kinds []graph.NodeKind, options CatalogOptions) (DataResourceList, error)

DataResources catalogs stored data resources. Passing no kinds catalogs every kind the graph model classifies as a data resource.

func (*Catalog) Events 

func (c *Catalog) Events(ctx context.Context, options CatalogOptions) (EventList, error)

Events catalogs event declarations with their producers, consumers, and handlers.

func (*Catalog) OrphanedEvents 

func (c *Catalog) OrphanedEvents(ctx context.Context, options CatalogOptions) (OrphanedEventList, error)

OrphanedEvents reports declared events whose local evidence is one-sided. An unresolved target that may be the missing counterpart downgrades the finding to unknown; it is never reported as a confirmed orphan.

type CatalogOptions 

type CatalogOptions struct {
	Repository   string
	Name         string
	PathPrefixes []string
	Limit        int
}

CatalogOptions bounds and filters a catalog request.

type ChannelConflict 

type ChannelConflict struct {
	Send    TransportFlow `json:"send"`
	Receive TransportFlow `json:"receive"`
}

type ConfigKey 

type ConfigKey struct {
	Resource
	Format  string `json:"format,omitempty"`
	Section string `json:"section,omitempty"`
	Defined bool   `json:"defined"`
	// WithheldProperties names node properties excluded from Properties
	// because they are not classified as non-secret configuration metadata.
	WithheldProperties []string    `json:"withheld_properties,omitempty"`
	Definitions        []UsageSite `json:"definitions"`
	Readers            []UsageSite `json:"readers"`
	References         []UsageSite `json:"references"`
}

ConfigKey reports where a configuration key is defined and read. Stored values are never included.

type ConfigKeyList 

type ConfigKeyList struct {
	Keys       []ConfigKey `json:"keys"`
	Unresolved []ConfigKey `json:"unresolved"`
	Truncated  bool        `json:"truncated"`
}

ConfigKeyList is the deterministic catalog of configuration keys.

type CoverageCategory 

type CoverageCategory = string

CoverageCategory names a concrete message-flow gap. 

const (
	ProducedWithoutConsumer CoverageCategory = "produced_without_consumer"
	EncodedWithoutSend      CoverageCategory = "encoded_without_send"
	ReceivedWithoutDecode   CoverageCategory = "received_without_decode"
	ChannelMismatch         CoverageCategory = "channel_mismatch"
	UnusedMessageMember     CoverageCategory = "unused_message_member"
	UnknownEvidence         CoverageCategory = "unknown_evidence"
)

type CoverageGap 

type CoverageGap struct {
	Category CoverageCategory `json:"category"`
	Message  string           `json:"message,omitempty"`
	Evidence []FlowEvidence   `json:"evidence,omitempty"`
}

type CoverageStatus 

type CoverageStatus string

CoverageStatus distinguishes complete evidence from proven gaps and cases where the graph cannot safely prove that evidence is absent. 

const (
	CoverageResolved        CoverageStatus = "resolved"
	CoverageMissingEvidence CoverageStatus = "missing_evidence"
	CoverageUnknown         CoverageStatus = "unknown"
)

type CrossRepositoryHop 

type CrossRepositoryHop struct {
	Direction ImpactDirection `json:"direction"`
	Edge      graph.Edge      `json:"edge"`
	Node      graph.Node      `json:"node"`
}

CrossRepositoryHop is an edge that federation resolved across a repository boundary, kept with the node on the far side.

type DataResourceList 

type DataResourceList struct {
	Resources  []Resource `json:"resources"`
	Unresolved []Resource `json:"unresolved"`
	Truncated  bool       `json:"truncated"`
}

DataResourceList is the deterministic catalog of stored data resources. Unresolved holds external targets that no indexed declaration matched; their presence is uncertainty, never proof that a resource is absent.

type DataResourceUsage 

type DataResourceUsage struct {
	Resource   Resource    `json:"resource"`
	Readers    []UsageSite `json:"readers"`
	Writers    []UsageSite `json:"writers"`
	References []UsageSite `json:"references"`
	Truncated  bool        `json:"truncated"`
}

DataResourceUsage partitions the edges that reach one data resource by semantic direction.

type Direction 

type Direction string
const (
	Outgoing Direction = "outgoing"
	Incoming Direction = "incoming"
	Both     Direction = "both"
)

type Endpoint 

type Endpoint struct {
	Resource
	Method        string         `json:"method"`
	Route         string         `json:"route"`
	Authority     string         `json:"authority,omitempty"`
	Exposers      []UsageSite    `json:"exposers"`
	Handlers      []UsageSite    `json:"handlers"`
	HandlerStatus BoundaryStatus `json:"handler_status"`
	// Middleware is the resolved outer-to-inner chain. UnresolvedMiddleware
	// keeps dynamic boundaries explicit instead of silently dropping them.
	Middleware           []UsageSite `json:"middleware"`
	UnresolvedMiddleware []UsageSite `json:"unresolved_middleware"`
	MiddlewareTruncated  bool        `json:"middleware_truncated"`
}

Endpoint is an HTTP declaration plus the graph evidence that exposes and handles it.

type EndpointList 

type EndpointList struct {
	Endpoints  []Endpoint `json:"endpoints"`
	Unresolved []Endpoint `json:"unresolved"`
	Truncated  bool       `json:"truncated"`
}

type Event 

type Event struct {
	Resource
	Form         string      `json:"form,omitempty"`
	Parameters   string      `json:"parameters,omitempty"`
	Declarations []UsageSite `json:"declarations"`
	Producers    []UsageSite `json:"producers"`
	Consumers    []UsageSite `json:"consumers"`
	Handlers     []UsageSite `json:"handlers"`
}

Event reports an event declaration with its publishers, subscribers, and handlers.

type EventList 

type EventList struct {
	Events     []Event `json:"events"`
	Unresolved []Event `json:"unresolved"`
	Truncated  bool    `json:"truncated"`
}

EventList is the deterministic catalog of events.

type FailureFlow 

type FailureFlow struct {
	Root            graph.Node        `json:"root"`
	ErrorReturns    []FailureFlowFact `json:"error_returns"`
	Escaping        []FailureFlowFact `json:"escaping"`
	Handled         []FailureFlowFact `json:"handled"`
	Panics          []FailureFlowFact `json:"panics"`
	Recoveries      []FailureFlowFact `json:"recoveries"`
	DeferredCleanup []FailureFlowFact `json:"deferred_cleanup"`
	Unresolved      int               `json:"unresolved"`
	Truncated       bool              `json:"truncated"`
}

FailureFlow separates a callable's typed error-return contract from actual escaping failures, handlers, panic/recovery sites, and deferred cleanup. Incoming relations are included as well, so selecting an error identity or callee answers which functions return, propagate, or handle it.

type FailureFlowFact 

type FailureFlowFact struct {
	Direction   Direction  `json:"direction"`
	Form        string     `json:"form,omitempty"`
	Conditional bool       `json:"conditional,omitempty"`
	Unresolved  bool       `json:"unresolved,omitempty"`
	Federated   bool       `json:"federated,omitempty"`
	Edge        graph.Edge `json:"edge"`
	Node        graph.Node `json:"node"`
}

FailureFlowFact keeps one failure or cleanup relation together with its far side and recognition evidence. Direction is outgoing when the selected root produced the fact and incoming when another symbol points at the root.

type FailureFlowOptions 

type FailureFlowOptions struct {
	Kind      graph.NodeKind
	Direction Direction
	Limit     int
}

type FlowEvidence 

type FlowEvidence struct {
	Repository  string            `json:"repository,omitempty"`
	Component   string            `json:"component,omitempty"`
	ComponentID string            `json:"component_id,omitempty"`
	Relation    graph.EdgeKind    `json:"relation"`
	EdgeID      string            `json:"edge_id"`
	FactID      string            `json:"fact_id,omitempty"`
	Node        Resource          `json:"node"`
	Location    graph.Location    `json:"location,omitempty"`
	Properties  map[string]string `json:"properties,omitempty"`
}

FlowEvidence retains the exact fact and graph edge behind one result.

type FlowUncertainty 

type FlowUncertainty struct {
	Reason     string         `json:"reason"`
	Message    string         `json:"message"`
	Evidence   []FlowEvidence `json:"evidence"`
	Candidates []Resource     `json:"candidates,omitempty"`
}

type GodotComposition 

type GodotComposition struct {
	Root               graph.Node      `json:"root"`
	SceneNodes         []graph.Node    `json:"scene_nodes"`
	OutboundInstances  []GodotRelation `json:"outbound_instances"`
	InboundInstances   []GodotRelation `json:"inbound_instances"`
	AttachedScripts    []GodotRelation `json:"attached_scripts"`
	ScriptAttachments  []GodotRelation `json:"script_attachments"`
	AutoloadTargets    []GodotRelation `json:"autoload_targets"`
	AutoloadExposures  []GodotRelation `json:"autoload_exposures"`
	Truncated          bool            `json:"truncated"`
	SceneNodesExplored int             `json:"scene_nodes_explored"`
}

GodotComposition answers the runtime composition questions for one Godot node: which scenes it instantiates, which scenes instantiate it, which scripts are attached where, and which autoload singletons expose it.

Every section is a set of resolved edges with their original evidence, so an unresolved or ambiguous reference appears as an external node rather than as a guessed edge or as a missing row.

type GodotCompositionOptions 

type GodotCompositionOptions struct {
	Depth int
	Limit int
	Kind  graph.NodeKind
}

GodotCompositionOptions bounds a composition report. Zero fields fall back to depth 8 for scene-tree traversal and 1000 relations per section. Kind restricts selector resolution to one node kind, which is how a caller names the scene rather than the script when a scene and its script share a canonical identity - they differ only by an extension the identity drops.

type GodotInteraction 

type GodotInteraction struct {
	Category  GodotInteractionCategory `json:"category"`
	Form      string                   `json:"form,omitempty"`
	Direction Direction                `json:"direction"`
	Edge      graph.Edge               `json:"edge"`
	Node      graph.Node               `json:"node"`
	Via       *graph.Node              `json:"via,omitempty"`
	Federated bool                     `json:"federated,omitempty"`
}

GodotInteraction is one gameplay-interaction fact kept with the node on the far side of the edge, the category it belongs to, and the operation form the producer recorded as evidence.

Via is the scene node that carried the evidence when the report was asked about the scene rather than the node, exactly as in a composition report. An unresolved far side stays an external node so a missing declaration or a signal whose owner could not be proved is visible rather than absent.

type GodotInteractionCategory 

type GodotInteractionCategory string

GodotInteractionCategory names one class of Godot gameplay interaction. The three categories are the filter vocabulary a caller narrows a report with, and an unknown value is an error rather than a filter that can never match. 

const (
	// GodotActionInteraction covers input-action declarations and uses.
	GodotActionInteraction GodotInteractionCategory = "action"
	// GodotGroupInteraction covers node-group membership, lookups, and
	// dispatches.
	GodotGroupInteraction GodotInteractionCategory = "group"
	// GodotSignalInteraction covers signal routing, whether a scene declared it
	// or a script established it.
	GodotSignalInteraction GodotInteractionCategory = "signal"
)

func GodotInteractionCategories 

func GodotInteractionCategories() []GodotInteractionCategory

GodotInteractionCategories returns the category vocabulary in report order.

func ParseGodotInteractionCategory 

func ParseGodotInteractionCategory(value string) (GodotInteractionCategory, error)

ParseGodotInteractionCategory validates a caller-supplied category. An empty value parses to the empty category, which every filter treats as "any".

type GodotInteractions 

type GodotInteractions struct {
	Root       graph.Node         `json:"root"`
	SceneNodes []graph.Node       `json:"scene_nodes"`
	Outbound   []GodotInteraction `json:"outbound"`
	Inbound    []GodotInteraction `json:"inbound"`
	// Unresolved counts the interactions whose far side is an unresolved
	// boundary node, so a caller can tell a fully wired report from one that
	// merely looks wired.
	Unresolved         int  `json:"unresolved"`
	Truncated          bool `json:"truncated"`
	SceneNodesExplored int  `json:"scene_nodes_explored"`
}

GodotInteractions is the gameplay-interaction report for one Godot node: the input actions it uses, the node groups it joins, leaves, inspects, and dispatches to, and the signal routes it takes part in, in both directions.

It is a sibling of GodotComposition rather than an extension of it. Composition answers what a scene is built from; interactions answer how it is wired at runtime, and the two sets of edges are disjoint.

type GodotInteractionsOptions 

type GodotInteractionsOptions struct {
	Depth      int
	Limit      int
	Kind       graph.NodeKind
	Direction  Direction
	Categories []GodotInteractionCategory
}

GodotInteractionsOptions bounds an interactions report. Zero fields fall back to depth 8 for scene-tree traversal, 1000 interactions per direction, both directions, and every category.

type GodotRelation 

type GodotRelation struct {
	Edge      graph.Edge  `json:"edge"`
	Node      graph.Node  `json:"node"`
	Via       *graph.Node `json:"via,omitempty"`
	Federated bool        `json:"federated,omitempty"`
}

GodotRelation is one Godot composition fact kept with the node on the far side of the edge and, when the evidence came from a scene node rather than the scene itself, the scene node that carried it.

type HandlerKind 

type HandlerKind string
const (
	HandlerHTTP  HandlerKind = "http"
	HandlerEvent HandlerKind = "event"
)

type HandlerList 

type HandlerList struct {
	Matches   []HandlerMatch `json:"matches"`
	Truncated bool           `json:"truncated"`
}

type HandlerMatch 

type HandlerMatch struct {
	Kind         HandlerKind    `json:"kind"`
	Subject      Resource       `json:"subject"`
	Method       string         `json:"method,omitempty"`
	Route        string         `json:"route,omitempty"`
	Event        string         `json:"event,omitempty"`
	Status       BoundaryStatus `json:"status"`
	Handlers     []UsageSite    `json:"handlers"`
	Repositories []string       `json:"repositories,omitempty"`
}

type ImpactDirection 

type ImpactDirection string

ImpactDirection names the two halves of a change-impact report. Upstream answers "who depends on the root" (incoming traversal); downstream answers "what does the root depend on" (outgoing traversal). 

const (
	Upstream   ImpactDirection = "upstream"
	Downstream ImpactDirection = "downstream"
)

type ImpactOptions 

type ImpactOptions struct {
	// Kind optionally restricts which node the selector may resolve to, so a
	// caller can say it means a method rather than one of its parameters.
	Kind               graph.NodeKind
	UpstreamDepth      int
	DownstreamDepth    int
	UpstreamLimit      int
	DownstreamLimit    int
	IncludeSource      bool
	SourceContextLines int
	SourceMaxLines     int
	SourceLimit        int
}

ImpactOptions bounds a report. Zero fields fall back to documented defaults: depth 4 and limit 1000 per direction, 2 context lines, 200 max source lines, and at most 10 excerpts.

type ImpactRelation 

type ImpactRelation struct {
	Direction ImpactDirection `json:"direction"`
	Edge      graph.Edge      `json:"edge"`
	Node      graph.Node      `json:"node"`
}

ImpactRelation is a config, data, or event relationship kept with the edge that proves it.

type ImpactReport 

type ImpactReport struct {
	Root            graph.Node           `json:"root"`
	Upstream        ImpactSection        `json:"upstream"`
	Downstream      ImpactSection        `json:"downstream"`
	ImpactedFiles   []ImpactedFile       `json:"impacted_files"`
	CrossRepository []CrossRepositoryHop `json:"cross_repository_hops"`
	Config          []ImpactRelation     `json:"config_relations"`
	Data            []ImpactRelation     `json:"data_relations"`
	Events          []ImpactRelation     `json:"event_relations"`
	Sources         []SourceExcerpt      `json:"sources,omitempty"`
	Truncated       bool                 `json:"truncated"`
}

ImpactReport is the full bidirectional change-impact answer for one root.

type ImpactSection 

type ImpactSection struct {
	Direction ImpactDirection  `json:"direction"`
	Depth     int              `json:"depth"`
	Relations []graph.EdgeKind `json:"relations"`
	Nodes     []ReachedNode    `json:"nodes"`
	Edges     []graph.Edge     `json:"edges"`
	Truncated bool             `json:"truncated"`
}

ImpactSection is one direction of a report, with the relations that produced it and its own truncation flag.

type ImpactedFile 

type ImpactedFile struct {
	Repository string   `json:"repository,omitempty"`
	Path       string   `json:"path"`
	NodeIDs    []string `json:"node_ids"`
	EdgeIDs    []string `json:"edge_ids"`
	Directions []string `json:"directions"`
	Federated  bool     `json:"federated,omitempty"`
}

ImpactedFile is one file touched by the report, deduplicated by repository identity plus canonical relative path while preserving every node and edge that caused its inclusion.

type LinkEvidence 

type LinkEvidence struct {
	EdgeID     string            `json:"edge_id"`
	FactID     string            `json:"fact_id,omitempty"`
	Relation   graph.EdgeKind    `json:"relation"`
	FromID     string            `json:"from_id"`
	ToID       string            `json:"to_id"`
	Location   graph.Location    `json:"location,omitempty"`
	Federated  bool              `json:"federated,omitempty"`
	Properties map[string]string `json:"properties,omitempty"`
}

LinkEvidence is the complete graph relation used to construct a topology link. Structured IDs remain authoritative even when a caller renders a diagram.

type MessageCoverage 

type MessageCoverage struct {
	Message         Resource            `json:"message"`
	Status          CoverageStatus      `json:"status"`
	Gaps            []CoverageGap       `json:"gaps"`
	UnknownEvidence []FlowEvidence      `json:"unknown_evidence"`
	Uncertainties   []FlowUncertainty   `json:"uncertainties"`
	Members         []MessageMemberFlow `json:"members"`
	Truncated       bool                `json:"truncated"`
}

type MessageCoverageList 

type MessageCoverageList struct {
	Messages  []MessageCoverage `json:"messages"`
	Truncated bool              `json:"truncated"`
}

type MessageCoverageOptions 

type MessageCoverageOptions struct {
	Repository   string         `json:"repository,omitempty"`
	Package      string         `json:"package,omitempty"`
	Message      string         `json:"message,omitempty"`
	Oneof        string         `json:"oneof,omitempty"`
	Direction    Direction      `json:"direction,omitempty"`
	Component    string         `json:"component,omitempty"`
	Status       CoverageStatus `json:"status,omitempty"`
	PathPrefixes []string       `json:"path_prefixes,omitempty"`
	Limit        int            `json:"limit,omitempty"`
}

type MessageFlow 

type MessageFlow struct {
	Message           Resource            `json:"message"`
	Status            CoverageStatus      `json:"status"`
	Bindings          []FlowEvidence      `json:"bindings"`
	Members           []MessageMemberFlow `json:"members"`
	Encoders          []FlowEvidence      `json:"encoders"`
	Decoders          []FlowEvidence      `json:"decoders"`
	Sends             []TransportFlow     `json:"sends"`
	Receives          []TransportFlow     `json:"receives"`
	Handlers          []MessageHandler    `json:"handlers"`
	Gaps              []CoverageGap       `json:"gaps"`
	UnknownEvidence   []FlowEvidence      `json:"unknown_evidence"`
	Uncertainties     []FlowUncertainty   `json:"uncertainties"`
	ChannelMismatches []ChannelConflict   `json:"channel_mismatches"`
	Truncated         bool                `json:"truncated"`
}

type MessageFlowAttempt 

type MessageFlowAttempt struct {
	Flow  MessageFlow
	Error error
}

MessageFlowAttempt preserves one selector's result or error in batch order. Error stays adapter-neutral so callers can retain typed ambiguity candidates.

type MessageFlowOptions 

type MessageFlowOptions struct {
	Repository string    `json:"repository,omitempty"`
	Component  string    `json:"component,omitempty"`
	Direction  Direction `json:"direction,omitempty"`
	Limit      int       `json:"limit,omitempty"`
}

type MessageFlowService 

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

func NewMessageFlow 

func NewMessageFlow(repository graph.TopologyRepository) *MessageFlowService

func (*MessageFlowService) Coverage 

func (s *MessageFlowService) Coverage(ctx context.Context, options MessageCoverageOptions) (MessageCoverageList, error)

func (*MessageFlowService) Flow 

func (s *MessageFlowService) Flow(ctx context.Context, selector string, options MessageFlowOptions) (MessageFlow, error)

func (*MessageFlowService) Flows 

func (s *MessageFlowService) Flows(ctx context.Context, selectors []string, options MessageFlowOptions) []MessageFlowAttempt

Flows evaluates several selectors against one bounded component snapshot. Results preserve selector order and isolate errors per selector.

type MessageHandler 

type MessageHandler struct {
	Evidence FlowEvidence   `json:"evidence"`
	Callers  []FlowEvidence `json:"callers"`
}

type MessageMemberFlow 

type MessageMemberFlow struct {
	Field     Resource       `json:"field"`
	Oneof     string         `json:"oneof,omitempty"`
	Status    CoverageStatus `json:"status"`
	Producers []FlowEvidence `json:"producers"`
	Consumers []FlowEvidence `json:"consumers"`
	Gaps      []CoverageGap  `json:"gaps"`
}

type OrphanCategory 

type OrphanCategory string

OrphanCategory names the shape of a missing counterpart. 

const (
	PublishedWithoutConsumer OrphanCategory = "published_without_consumer"
	ConsumedWithoutProducer  OrphanCategory = "consumed_without_producer"
	DeclaredWithNeither      OrphanCategory = "declared_with_neither"
)

type OrphanStatus 

type OrphanStatus string

OrphanStatus separates a confirmed orphan from one whose missing counterpart may exist behind an unresolved target. 

const (
	OrphanConfirmed OrphanStatus = "orphaned"
	OrphanUnknown   OrphanStatus = "unknown"
)

type OrphanedEvent 

type OrphanedEvent struct {
	Event    Event          `json:"event"`
	Category OrphanCategory `json:"category"`
	Status   OrphanStatus   `json:"status"`
	// UnresolvedProducers and UnresolvedConsumers count edges that reach an
	// unresolved external target this event may be. Any such edge makes the
	// status unknown rather than orphaned. Counterpart evidence uses the
	// fixed MaxCatalogLimit rather than the caller's bound, because a tighter
	// bound would only turn more findings unknown.
	UnresolvedProducers    int         `json:"unresolved_producers"`
	UnresolvedConsumers    int         `json:"unresolved_consumers"`
	UnresolvedCounterparts []UsageSite `json:"unresolved_counterparts,omitempty"`
}

OrphanedEvent reports one event whose local evidence is one-sided.

type OrphanedEventList 

type OrphanedEventList struct {
	Events    []OrphanedEvent `json:"events"`
	Truncated bool            `json:"truncated"`
}

OrphanedEventList is the deterministic orphan report.

type OutboundRequest 

type OutboundRequest struct {
	Source      Resource       `json:"source"`
	Method      string         `json:"method"`
	Route       string         `json:"route"`
	Scheme      string         `json:"scheme,omitempty"`
	Authority   string         `json:"authority,omitempty"`
	Status      BoundaryStatus `json:"status"`
	Target      Endpoint       `json:"target"`
	Destination Endpoint       `json:"destination,omitzero"`
	Candidates  []Endpoint     `json:"candidates"`
	Evidence    LinkEvidence   `json:"evidence"`
	Truncated   bool           `json:"truncated"`
}

OutboundRequest reports one underlying requests fact. Destination is filled only for one exact endpoint or for an unresolved external boundary. Several exact declarations are returned as Candidates and never silently selected.

type OutboundRequestList 

type OutboundRequestList struct {
	Requests  []OutboundRequest `json:"requests"`
	Truncated bool              `json:"truncated"`
}

type Path 

type Path struct {
	From  graph.Node   `json:"from"`
	To    graph.Node   `json:"to"`
	Nodes []graph.Node `json:"nodes"`
	Edges []graph.Edge `json:"edges"`
}

type ReachedNode 

type ReachedNode struct {
	Depth int        `json:"depth"`
	Node  graph.Node `json:"node"`
}

type Resource 

type Resource struct {
	Repository    string            `json:"repository,omitempty"`
	Component     string            `json:"component,omitempty"`
	ComponentID   string            `json:"component_id,omitempty"`
	ID            string            `json:"id"`
	Kind          graph.NodeKind    `json:"kind"`
	Name          string            `json:"name"`
	QualifiedName string            `json:"qualified_name"`
	ObjectKind    string            `json:"object_kind,omitempty"`
	Dialect       string            `json:"dialect,omitempty"`
	Persistence   string            `json:"persistence,omitempty"`
	Language      string            `json:"language,omitempty"`
	Location      graph.Location    `json:"location,omitempty"`
	Unresolved    bool              `json:"unresolved,omitempty"`
	Properties    map[string]string `json:"properties,omitempty"`
}

Resource describes one catalog entry. Common metadata is normalized into typed fields while the parser's own node properties remain available.

type Service 

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

func NewService 

func NewService(repository graph.QueryRepository) *Service

func (*Service) FailureFlow 

func (s *Service) FailureFlow(ctx context.Context, selector string, options FailureFlowOptions) (FailureFlow, error)

FailureFlow resolves selector and groups only the versioned failure-flow vocabulary already present in the graph. It never re-parses source.

func (*Service) Find 

func (s *Service) Find(ctx context.Context, term string, limit int) ([]graph.Node, error)

func (*Service) FindTests 

func (s *Service) FindTests(ctx context.Context, selector string, options TestCoverageOptions) (TestCoverageReport, error)

FindTests reports tests that structurally reach one production declaration.

func (*Service) GodotComposition 

func (s *Service) GodotComposition(ctx context.Context, selector string, options GodotCompositionOptions) (GodotComposition, error)

GodotComposition resolves the selector and returns its deterministic Godot composition report. Resolution errors (ErrNotFound, *AmbiguousError) propagate unchanged and never yield a partial report.

func (*Service) GodotInteractions 

func (s *Service) GodotInteractions(ctx context.Context, selector string, options GodotInteractionsOptions) (GodotInteractions, error)

GodotInteractions resolves the selector and returns its deterministic Godot interaction report. Resolution errors (ErrNotFound, *AmbiguousError) propagate unchanged and never yield a partial report.

func (*Service) Impact 

func (s *Service) Impact(ctx context.Context, selector string, options ImpactOptions) (ImpactReport, error)

Impact resolves the selector and returns a deterministic bidirectional change-impact report. Resolution errors (ErrNotFound, *AmbiguousError) propagate unchanged and never yield a partial report.

func (*Service) Neighborhood 

func (s *Service) Neighborhood(ctx context.Context, selector string, kind graph.NodeKind, depth int, direction Direction, relations []graph.EdgeKind, limit int) (Traversal, error)

Neighborhood walks edges from a resolved root. kind optionally restricts which node the selector may resolve to; an empty kind accepts any kind.

func (*Service) Resolve 

func (s *Service) Resolve(ctx context.Context, selector string) (graph.Node, error)

Resolve resolves a selector to exactly one node, or reports why it cannot. It is the single resolution path behind every CLI command and MCP tool.

func (*Service) ResolveKind 

func (s *Service) ResolveKind(ctx context.Context, selector string, kind graph.NodeKind) (graph.Node, error)

ResolveKind resolves a selector restricted to one node kind; an empty kind accepts any kind. A caller that means the function rather than one of its parameters can say so instead of guessing at the candidate list.

The contract is that resolution either returns one node on evidence or fails, never one of several equally good matches. That holds because every decision below is made from graph.NodeMatchGroup totals, which cover the whole graph, rather than from the truncated candidate list:

  • Only the strongest match level contributes. A substring match can never make an exact name match ambiguous.
  • Within a level, case-sensitive matches decide uniqueness whenever any exist, so "impact" resolves to App.impact rather than tying with Service.Impact. Case-insensitive-only matches remain in the reported candidate list, because they are what the caller most likely has to disambiguate between.
  • A candidate whose qualified name merely extends another candidate's is a descendant of it, not a rival: a method is preferred over its own parameters and local variables.
  • Narrowing a truncated list is refused outright, because the nodes that were cut off could be equally good matches.

func (*Service) ResolveKindInRepository 

func (s *Service) ResolveKindInRepository(ctx context.Context, selector string, kind graph.NodeKind, repository string) (graph.Node, error)

ResolveKindInRepository applies the shared fail-closed selector rules inside one stable indexed repository. An empty repository preserves global/federated resolution.

func (*Service) ShortestPath 

func (s *Service) ShortestPath(ctx context.Context, fromSelector, toSelector string, kind graph.NodeKind, direction Direction, relations []graph.EdgeKind, limit int) (Path, error)

ShortestPath walks from one resolved node to another. kind optionally restricts both endpoints to one node kind.

func (*Service) TestCoverage 

func (s *Service) TestCoverage(ctx context.Context, selector string, options TestCoverageOptions) (TestCoverageReport, error)

TestCoverage reports production targets structurally reached by one test.

func (*Service) WithSourceReader 

func (s *Service) WithSourceReader(reader SourceReader) *Service

WithSourceReader returns a copy of the service that can attach source excerpts. The receiver is left unchanged so a shared service stays safe for concurrent use. 

type ServiceLink struct {
	ID            string          `json:"id"`
	FromServiceID string          `json:"from_service_id"`
	ToServiceID   string          `json:"to_service_id"`
	Kind          ServiceLinkKind `json:"kind"`
	Name          string          `json:"name"`
	Status        BoundaryStatus  `json:"status"`
	Method        string          `json:"method,omitempty"`
	Route         string          `json:"route,omitempty"`
	Scheme        string          `json:"scheme,omitempty"`
	Authority     string          `json:"authority,omitempty"`
	Event         string          `json:"event,omitempty"`
	EndpointIDs   []string        `json:"endpoint_ids,omitempty"`
	EventIDs      []string        `json:"event_ids,omitempty"`
	EdgeIDs       []string        `json:"edge_ids"`
	FactIDs       []string        `json:"fact_ids,omitempty"`
	Federated     bool            `json:"federated,omitempty"`
	SourceNodes   []Resource      `json:"source_nodes"`
	TargetNodes   []Resource      `json:"target_nodes"`
	Evidence      []LinkEvidence  `json:"evidence"`
	Truncated     bool            `json:"truncated"`
}

type ServiceLinkKind 

type ServiceLinkKind string
const (
	LinkHTTP  ServiceLinkKind = "http"
	LinkEvent ServiceLinkKind = "event"
)

type ServiceNode 

type ServiceNode struct {
	ID          string     `json:"id"`
	Repository  string     `json:"repository,omitempty"`
	Component   string     `json:"component,omitempty"`
	ComponentID string     `json:"component_id,omitempty"`
	Label       string     `json:"label"`
	External    bool       `json:"external,omitempty"`
	Components  []Resource `json:"components"`
}

ServiceNode separates stable repository/component identity from its presentation label. External nodes are explicit unresolved or ambiguous destinations.

type ServiceTopology 

type ServiceTopology struct {
	Services  []ServiceNode `json:"services"`
	Links     []ServiceLink `json:"links"`
	Truncated bool          `json:"truncated"`
}

type SourceExcerpt 

type SourceExcerpt struct {
	NodeID     string `json:"node_id"`
	Repository string `json:"repository,omitempty"`
	Branch     string `json:"branch,omitempty"`
	Path       string `json:"path"`
	StartLine  int    `json:"start_line"`
	EndLine    int    `json:"end_line"`
	Content    string `json:"content"`
	Truncated  bool   `json:"truncated"`
}

SourceExcerpt is a bounded snippet of the worktree backing one node.

type SourceReader 

type SourceReader interface {
	ReadNodeSource(ctx context.Context, nodeID string, contextLines, maxLines int) (SourceExcerpt, error)
}

SourceReader is the narrow port used to attach bounded source excerpts to a report. internal/source imports internal/query, so this package must not import it back; the CLI and MCP layers supply an adapter over source.Service instead. A node ID is a valid source selector, which makes that adapter trivial.

type TestCoverageMatch 

type TestCoverageMatch struct {
	Test        graph.Node   `json:"test"`
	Target      graph.Node   `json:"target"`
	Direct      bool         `json:"direct"`
	Depth       int          `json:"depth"`
	Designation string       `json:"designation"`
	Nodes       []graph.Node `json:"nodes"`
	Edges       []graph.Edge `json:"edges"`
}

TestCoverageMatch is one evidence-backed structural relationship. Nodes and Edges are ordered from the test declaration to the production target.

type TestCoverageOptions 

type TestCoverageOptions struct {
	Depth int            `json:"depth,omitempty"`
	Limit int            `json:"limit,omitempty"`
	Kind  graph.NodeKind `json:"kind,omitempty"`
}

TestCoverageOptions bounds structural helper expansion. It never requests or represents runtime execution coverage.

type TestCoverageReport 

type TestCoverageReport struct {
	Root        graph.Node          `json:"root"`
	Direction   string              `json:"direction"`
	Designation string              `json:"designation"`
	Depth       int                 `json:"depth"`
	Limit       int                 `json:"limit"`
	Matches     []TestCoverageMatch `json:"matches"`
	Truncated   bool                `json:"truncated"`
}

TestCoverageReport is deliberately structural rather than runtime coverage. Truncated is set for relation overflow, depth/size exhaustion, or a helper cycle, so incomplete evidence is never presented as exhaustive.

type Topology 

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

Topology owns endpoint and service-boundary interpretation. Storage only enumerates exact node kinds and graph adjacency.

func NewTopology 

func NewTopology(repository graph.TopologyRepository) *Topology

func (*Topology) Endpoints 

func (t *Topology) Endpoints(ctx context.Context, options TopologyOptions) (EndpointList, error)

func (*Topology) Handlers 

func (t *Topology) Handlers(ctx context.Context, options TopologyOptions) (HandlerList, error)

func (*Topology) OutboundRequests 

func (t *Topology) OutboundRequests(ctx context.Context, options TopologyOptions) (OutboundRequestList, error)

func (*Topology) ServiceTopology 

func (t *Topology) ServiceTopology(ctx context.Context, options TopologyOptions) (ServiceTopology, error)

type TopologyOptions 

type TopologyOptions struct {
	Repository   string    `json:"repository,omitempty"`
	Component    string    `json:"component,omitempty"`
	Method       string    `json:"method,omitempty"`
	Route        string    `json:"route,omitempty"`
	Event        string    `json:"event,omitempty"`
	Direction    Direction `json:"direction,omitempty"`
	PathPrefixes []string  `json:"path_prefixes,omitempty"`
	Limit        int       `json:"limit,omitempty"`
}

TopologyOptions filters and bounds endpoint, handler, request, and service topology queries. Repository and Component select independently stable indexed ownership identities; labels are presentation-only.

type TransportFlow 

type TransportFlow struct {
	Evidence    FlowEvidence   `json:"evidence"`
	Direction   string         `json:"direction"`
	API         string         `json:"api,omitempty"`
	Channel     string         `json:"channel,omitempty"`
	Reliability string         `json:"reliability,omitempty"`
	Status      CoverageStatus `json:"status"`
	Sources     []FlowEvidence `json:"sources"`
}

type Traversal 

type Traversal struct {
	Root      graph.Node    `json:"root"`
	Nodes     []ReachedNode `json:"nodes"`
	Edges     []graph.Edge  `json:"edges"`
	Direction Direction     `json:"direction"`
	Truncated bool          `json:"truncated"`
}

type UsageSite 

type UsageSite struct {
	Relation  graph.EdgeKind    `json:"relation"`
	EdgeID    string            `json:"edge_id"`
	FactID    string            `json:"fact_id,omitempty"`
	Node      graph.Node        `json:"node"`
	Location  graph.Location    `json:"location,omitempty"`
	Federated bool              `json:"federated,omitempty"`
	Evidence  map[string]string `json:"evidence,omitempty"`
}

UsageSite is one edge of evidence that a node uses a catalog entry.

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.