graph

type BulkIndexRepository ¶ added in v0.2.2

type BulkIndexRepository interface {
	ReplaceFiles(context.Context, []FileReplacement) error
}

BulkIndexRepository optionally replaces several files in one durable step. Indexers fall back to ReplaceFile per file when a repository does not offer it, so the capability only ever changes how many files share a commit, never which evidence is stored.

type BulkLoadRepository ¶ added in v0.2.2

type BulkLoadRepository interface {
	BeginBulkLoad(context.Context) error
	EndBulkLoad(context.Context) error
}

BulkLoadRepository optionally reorganizes storage around an initial load of a whole repository. Indexers announce the boundaries; whether anything is reorganized, and what, is the adapter's decision, and a repository that does not offer the capability indexes exactly as before.

type CanonicalMessagePage ¶

type CanonicalMessagePage struct {
	Items     []ScopedNode
	Truncated bool
}

CanonicalMessagePage reports whether more matching canonical messages exist beyond the requested bound.

type CanonicalMessageQuery ¶

type CanonicalMessageQuery struct {
	Repository   string
	Package      string
	Message      string
	PathPrefixes []string
	Limit        int
}

CanonicalMessageQuery selects locally declared protocol-message types before applying its bound. Package and Message are exact semantic filters rather than post-enumeration presentation filters.

func (q CanonicalMessageQuery) Validate() error

type CanonicalMessageRepository ¶

type CanonicalMessageRepository interface {
	CanonicalMessages(context.Context, CanonicalMessageQuery) (CanonicalMessagePage, error)
}

CanonicalMessageRepository is the narrow bounded enumeration port used by message coverage. Implementations filter authoritative message declarations before sorting and limiting.

type CatalogRepository ¶

type CatalogRepository interface {
	Node(context.Context, string) (Node, error)
	NodeListRepository
	RelationEdgeRepository
}

CatalogRepository is the read port the data, configuration, and event catalogs depend on.

type Counts ¶

type Counts struct {
	Files    int            `json:"files"`
	Nodes    int            `json:"nodes"`
	Facts    int            `json:"facts"`
	Edges    int            `json:"edges"`
	External int            `json:"external_nodes"`
	ByKind   map[string]int `json:"nodes_by_kind"`
	ByEdge   map[string]int `json:"edges_by_kind"`
}

type Diagnostic ¶

type Diagnostic struct {
	Path    string `json:"path"`
	Line    int    `json:"line,omitempty"`
	Level   string `json:"level"`
	Message string `json:"message"`
}

type Edge ¶

type Edge struct {
	ID         string            `json:"id"`
	FromID     string            `json:"from_id"`
	ToID       string            `json:"to_id"`
	Kind       EdgeKind          `json:"kind"`
	Producer   string            `json:"producer,omitempty"`
	Location   Location          `json:"location,omitempty"`
	Properties map[string]string `json:"properties,omitempty"`
	FactID     string            `json:"fact_id,omitempty"`
}

func DirectTestEdge(source, target Node, evidence Edge) (Edge, bool)

type EdgeKind ¶

type EdgeKind string

const (
	EdgeContains EdgeKind = "contains"
	EdgeDeclares EdgeKind = "declares"
	EdgeImports  EdgeKind = "imports"
	EdgeExports  EdgeKind = "exports"
	EdgeCalls    EdgeKind = "calls"
	// EdgeTests is direct, uniquely resolved structural test evidence. Helper
	// expansion stays query-time and never persists synthetic transitive edges.
	EdgeTests       EdgeKind = "tests"
	EdgeEmbeds      EdgeKind = "embeds"
	EdgeExtends     EdgeKind = "extends"
	EdgeImplements  EdgeKind = "implements"
	EdgeReadsConfig EdgeKind = "reads_config"
	EdgeDefines     EdgeKind = "defines"
	EdgeExposes     EdgeKind = "exposes"
	EdgeHandledBy   EdgeKind = "handled_by"
	// uses_middleware connects an endpoint to one callable in its effective
	// outer-to-inner middleware chain. Order and framework form are edge
	// evidence, keeping the relation language-neutral.
	EdgeUsesMiddleware EdgeKind = "uses_middleware"
	EdgePublishes      EdgeKind = "publishes"
	EdgeSubscribes     EdgeKind = "subscribes"
	EdgeReferences     EdgeKind = "references"
	EdgeReads          EdgeKind = "reads"
	EdgeWrites         EdgeKind = "writes"
	// encodes and decodes connect application code to a language-neutral
	// protocol declaration. Field-level protocol access continues to use the
	// shared reads and writes relations, distinguished by edge properties.
	EdgeEncodes EdgeKind = "encodes"
	EdgeDecodes EdgeKind = "decodes"
	// sends and receives connect application code to a stable transport
	// operation callsite. carries connects that operation to a canonical
	// protocol message only when payload provenance proves the relationship.
	EdgeSends     EdgeKind = "sends"
	EdgeReceives  EdgeKind = "receives"
	EdgeCarries   EdgeKind = "carries"
	EdgeHasField  EdgeKind = "has_field"
	EdgeAssigns   EdgeKind = "assigns"
	EdgeReturns   EdgeKind = "returns"
	EdgePasses    EdgeKind = "passes"
	EdgeRequests  EdgeKind = "requests"
	EdgeDependsOn EdgeKind = "depends_on"
	EdgeDocuments EdgeKind = "documents"
	// generated_from connects a language binding projection to the canonical
	// declaration that defines its wire/schema identity. Generated source is
	// evidence for a projection, never a second schema authority.
	EdgeGeneratedFrom EdgeKind = "generated_from"

	// Failure-flow relations are language-neutral even though Go is currently
	// their only producer. returns_error describes a callable's typed result
	// contract; propagates_error and wraps_error describe actual exits;
	// handles_error records a consuming conditional action. panics, recovers,
	// and defers keep abrupt exits and cleanup separate from ordinary calls.
	// Recognition details such as return, join, comparison, switch, or recovery
	// live in the edge's "form" property.
	EdgeReturnsError    EdgeKind = "returns_error"
	EdgePropagatesError EdgeKind = "propagates_error"
	EdgeHandlesError    EdgeKind = "handles_error"
	EdgeWrapsError      EdgeKind = "wraps_error"
	EdgePanics          EdgeKind = "panics"
	EdgeRecovers        EdgeKind = "recovers"
	EdgeDefers          EdgeKind = "defers"

	// Godot composition relations. instantiates records a scene instance
	// (nested or inherited) and is deliberately distinct from extends so
	// scene composition is never mislabeled as language class inheritance.
	// attaches_script records a script bound to a scene node, scene, or
	// resource. autoloads records the target a project.godot autoload
	// declaration exposes globally.
	EdgeInstantiates   EdgeKind = "instantiates"
	EdgeAttachesScript EdgeKind = "attaches_script"
	EdgeAutoloads      EdgeKind = "autoloads"

	// Godot gameplay-interaction relations. uses_input_action records a read of
	// a declared input action; in_group records that a node belongs to (or
	// leaves) a node group; uses_group records a lookup of, or a dispatch to,
	// the members of a group without asserting membership.
	//
	// The operation that produced each edge lives in its "form" property rather
	// than in a separate edge kind, because direction and meaning are shared
	// within each relation: a group lookup and a group call both read the
	// group's members, and add_to_group and remove_from_group both name a
	// membership between the same two nodes. A membership test (is_in_group) is
	// deliberately a uses_group lookup and never an in_group edge: asking
	// whether a node is in a group is not evidence that it is.
	EdgeUsesInputAction EdgeKind = "uses_input_action"
	EdgeInGroup         EdgeKind = "in_group"
	EdgeUsesGroup       EdgeKind = "uses_group"
)

func EdgeKinds() []EdgeKind

type ExternalEdgeRepository ¶

type ExternalEdgeRepository interface {
	ExternalEdgesTo(context.Context, Node) ([]Edge, error)
}

ExternalEdgeRepository exposes unresolved edge targets for cross-repository federation. It remains separate so traversal use cases do not require it.

type ExternalNodeRepository ¶

type ExternalNodeRepository interface {
	ExternalNodesMatching(context.Context, Node) ([]Node, error)
}

ExternalNodeRepository enumerates unresolved boundary nodes that a declared node can replace during federation. It returns exact name equivalence only; relation evidence is still loaded exclusively through RelationEdgeRepository.

type ExternalRequestEdge ¶

type ExternalRequestEdge struct {
	Edge   Edge
	Source Node
	Target Node
}

ExternalRequestEdge is one persisted request boundary plus both endpoint and source nodes. Federation consumes these in bounded pages to build a symmetric route projection without per-endpoint adjacency queries.

type ExternalRequestEdgePage ¶

type ExternalRequestEdgePage struct {
	Items []ExternalRequestEdge
	Next  string
}

type ExternalRequestEdgeRepository ¶

type ExternalRequestEdgeRepository interface {
	ExternalRequestEdges(context.Context, string, int) (ExternalRequestEdgePage, error)
}

type Fact ¶

type Fact struct {
	ID         string            `json:"id"`
	FromID     string            `json:"from_id"`
	Source     string            `json:"source,omitempty"`
	SourceKind NodeKind          `json:"source_kind,omitempty"`
	Kind       EdgeKind          `json:"kind"`
	Producer   string            `json:"producer,omitempty"`
	TargetID   string            `json:"target_id,omitempty"`
	Target     string            `json:"target,omitempty"`
	TargetKind NodeKind          `json:"target_kind,omitempty"`
	Location   Location          `json:"location,omitempty"`
	Properties map[string]string `json:"properties,omitempty"`
	OwnerFile  string            `json:"-"`
}

func (f Fact) ValidateSourceLocator() error

type FileCatalog ¶

type FileCatalog interface {
	Files(context.Context) (map[string]FileRecord, error)
}

FileCatalog exposes the indexed file records of one repository index. It is the authority for search membership; search never walks the filesystem.

type FileRecord ¶

type FileRecord struct {
	Path       string `json:"path"`
	Hash       string `json:"hash"`
	Language   string `json:"language"`
	Size       int64  `json:"size"`
	ModifiedNS int64  `json:"modified_ns"`
	IndexedAt  string `json:"indexed_at"`
}

type FileReplacement ¶ added in v0.2.2

type FileReplacement struct {
	File   FileRecord
	Parsed ParseResult
}

FileReplacement is one file's record paired with the evidence parsed from it.

type HydratedRelationEdge ¶

type HydratedRelationEdge struct {
	Edge        Edge
	Counterpart Node
	// Repository identifies the indexed repository that owns Counterpart.
	// Single-repository callers may leave it empty and provide their known scope.
	Repository string
}

HydratedRelationEdge pairs an edge with the node opposite the request's subject. Adapters return the pair atomically so catalogs never perform an N+1 node lookup or silently omit a missing counterpart.

type IndexRepository ¶

type IndexRepository interface {
	Meta(context.Context, string) (string, error)
	SetMeta(context.Context, string, string) error
	Files(context.Context) (map[string]FileRecord, error)
	ReplaceFile(context.Context, FileRecord, ParseResult) error
	ReplaceOwner(context.Context, string, ParseResult) error
	RemoveFiles(context.Context, []string) error
	Reconcile(context.Context) error
	Counts(context.Context) (Counts, error)
}

IndexRepository is the narrow persistence port used by the indexing use case.

type InstrumentedIndexRepository ¶

type InstrumentedIndexRepository interface {
	ReconcileWithStats(context.Context, ReconciliationObserver) (ReconciliationStats, error)
}

InstrumentedIndexRepository optionally exposes reconciliation progress. Indexers retain compatibility with repositories that implement only IndexRepository.

type InstrumentedWriteRepository ¶

type InstrumentedWriteRepository interface {
	WriteStats() WriteStats
}

InstrumentedWriteRepository optionally exposes cumulative bounded-write metrics. Indexers take a per-run delta so a repository can be reused.

type Location ¶

type Location struct {
	Path    string `json:"path,omitempty"`
	Line    int    `json:"line,omitempty"`
	Column  int    `json:"column,omitempty"`
	EndLine int    `json:"end_line,omitempty"`
}

type Node ¶

type Node struct {
	ID            string            `json:"id"`
	Kind          NodeKind          `json:"kind"`
	Name          string            `json:"name"`
	QualifiedName string            `json:"qualified_name"`
	Language      string            `json:"language,omitempty"`
	Location      Location          `json:"location,omitempty"`
	Properties    map[string]string `json:"properties,omitempty"`
	OwnerFile     string            `json:"-"`
	External      bool              `json:"external,omitempty"`
}

type NodeKind ¶

type NodeKind string

const (
	KindRepository NodeKind = "repository"
	KindComponent  NodeKind = "component"
	KindFile       NodeKind = "file"
	KindPackage    NodeKind = "package"
	KindModule     NodeKind = "module"
	KindFunction   NodeKind = "function"
	KindMethod     NodeKind = "method"
	// KindTest is a statically recognized test declaration. Subtype and
	// framework details remain properties so one language-neutral kind covers
	// Go tests, benchmarks, fuzz tests, examples, and Godot test methods.
	KindTest       NodeKind = "test"
	KindType       NodeKind = "type"
	KindClass      NodeKind = "class"
	KindInterface  NodeKind = "interface"
	KindField      NodeKind = "field"
	KindVariable   NodeKind = "variable"
	KindParameter  NodeKind = "parameter"
	KindTable      NodeKind = "table"
	KindView       NodeKind = "view"
	KindColumn     NodeKind = "column"
	KindIndex      NodeKind = "index"
	KindConfigKey  NodeKind = "config_key"
	KindEndpoint   NodeKind = "endpoint"
	KindEvent      NodeKind = "event"
	KindDocSection NodeKind = "document_section"
	KindExternal   NodeKind = "external"

	// Godot runtime composition vocabulary. Scenes and resources are the
	// engine's two text-resource forms, scene nodes are the tree a scene
	// declares, and an autoload is a globally available singleton declared in
	// project.godot. They are distinct kinds rather than generic modules and
	// variables so composition questions are answerable by kind and edge
	// instead of property inspection.
	KindGodotScene     NodeKind = "godot_scene"
	KindGodotResource  NodeKind = "godot_resource"
	KindGodotSceneNode NodeKind = "godot_scene_node"
	KindGodotAutoload  NodeKind = "godot_autoload"

	// Godot gameplay-interaction vocabulary. An input action is a named action
	// declared in a project.godot [input] section and read back by Input and
	// InputMap calls; a node group is a named set of scene nodes declared in a
	// [global_group] section and joined, tested, and dispatched to by name.
	// Both are project-scoped declarations rather than generic config keys, so
	// "who uses this action" and "who is in this group" are answerable by kind
	// and edge instead of by matching a key-name prefix.
	KindGodotInputAction NodeKind = "godot_input_action"
	KindGodotNodeGroup   NodeKind = "godot_node_group"

	// A transport operation is one evidence-backed send or receive callsite.
	// It is deliberately not a channel or peer node: equal channel values do
	// not establish communication between two endpoints.
	KindTransportOperation NodeKind = "transport_operation"
)

func DataResourceKinds() []NodeKind

func NodeKinds() []NodeKind

func ParseNodeKind(value string) (NodeKind, error)

type NodeListQuery ¶

type NodeListQuery struct {
	Kinds      []NodeKind
	Name       string
	Repository string
	// PathPrefixes are normalized repository-relative segment prefixes. They
	// filter canonical node locations before the per-kind Limit is applied.
	PathPrefixes []string
	// Visibility defaults to LocalNodes so a catalog never silently mixes
	// declarations with unresolved external targets.
	Visibility NodeVisibility
	// Limit bounds the rows returned for each requested kind. Callers that
	// merge several kinds apply their own total bound and report truncation.
	Limit int
}

NodeListQuery selects nodes for catalog use cases. It expresses enumeration only: exact kinds, an optional name fragment, and explicit bounds.

type NodeListRepository ¶

type NodeListRepository interface {
	Repositories(context.Context) ([]string, error)
	ListNodesByKind(context.Context, NodeListQuery) ([]ScopedNode, error)
}

NodeListRepository enumerates nodes by exact kind and attributes them to an indexed repository. Adapters only enumerate; catalog semantics such as usage direction and orphan classification stay in the query use cases.

type NodeMatchGroup ¶

type NodeMatchGroup struct {
	Level NodeMatchLevel `json:"level"`
	// External marks a group that holds external boundary nodes because no local
	// declaration matched at this level. It makes the group weaker evidence than a
	// local group at the same level, which matters when merging federated members.
	External bool   `json:"external,omitempty"`
	Nodes    []Node `json:"nodes"`
	Strict   int    `json:"strict"`
	Total    int    `json:"total"`
}

NodeMatchGroup is the complete evidence for a selector at one level.

Adapters must honor three rules, because selector resolution is only sound if they hold:

• The group is the strongest evidence that matched anything, ranked by StrongerThan: a case-sensitive match outranks a case-insensitive-only one at any level, then a stronger level wins, then a local declaration beats an external boundary node. Weaker evidence is not reported, so a substring match never competes with an exact name match and an unresolved boundary node never competes with a real declaration.
• Total and Strict count every match at that level in the graph, whether or not it fits in Nodes. Truncation must therefore be observable, and a truncated list can never silently narrow a match set.
• Nodes lists case-sensitive ("strict") matches first and is otherwise deterministically ordered, so the first Strict entries of Nodes are exactly the strict matches whenever Strict <= len(Nodes).

func (g NodeMatchGroup) StrongerThan(other NodeMatchGroup) bool

func (g NodeMatchGroup) Truncated() bool

type NodeMatchLevel ¶

type NodeMatchLevel string

NodeMatchLevel names one class of evidence that a selector matched a node. Levels are ordered: a qualified-name match is stronger evidence than a bare name match, which is stronger than a substring match. Resolution never mixes levels, so a weaker match can never make a stronger one ambiguous.

const (
	// MatchNone is the zero level, reported when a selector matched nothing.
	MatchNone NodeMatchLevel = ""
	// MatchQualifiedName means qualified_name equals the selector.
	MatchQualifiedName NodeMatchLevel = "qualified_name"
	// MatchName means name equals the selector.
	MatchName NodeMatchLevel = "name"
	// MatchSubstring means name or qualified_name contains the selector.
	MatchSubstring NodeMatchLevel = "substring"
)

func (l NodeMatchLevel) Rank() int

func (l NodeMatchLevel) Stronger(other NodeMatchLevel) bool

type NodeMatchQuery ¶

type NodeMatchQuery struct {
	Selector   string   `json:"selector"`
	Kind       NodeKind `json:"kind,omitempty"`
	Repository string   `json:"repository,omitempty"`
	Limit      int      `json:"limit,omitempty"`
}

NodeMatchQuery asks an adapter for the match evidence behind one selector. Kind is an optional filter: an empty kind matches any kind. Limit bounds only the returned node list, never the reported totals, so a caller can always tell that a list was truncated.

type NodeVisibility ¶

type NodeVisibility string

NodeVisibility selects whether an enumeration returns locally declared nodes, unresolved external nodes, or both.

const (
	LocalNodes    NodeVisibility = "local"
	ExternalNodes NodeVisibility = "external"
	AllNodes      NodeVisibility = "all"
)

type ParseResult ¶

type ParseResult struct {
	Nodes       []Node
	Facts       []Fact
	Diagnostics []Diagnostic
}

type QueryRepository ¶

type QueryRepository interface {
	SearchNodes(context.Context, string, int) ([]Node, error)
	// MatchNodes returns the strongest non-empty match evidence for a selector.
	// Selector resolution depends on its contract; see NodeMatchGroup.
	MatchNodes(context.Context, NodeMatchQuery) (NodeMatchGroup, error)
	Node(context.Context, string) (Node, error)
	EdgesFrom(context.Context, string) ([]Edge, error)
	EdgesTo(context.Context, string) ([]Edge, error)
}

QueryRepository is the read-only port used by graph traversal use cases.

type ReadRepository ¶

type ReadRepository interface {
	QueryRepository
	StatusRepository
}

type ReconciliationObserver ¶

type ReconciliationObserver func(ReconciliationStats) error

ReconciliationObserver runs immediately after a reconciliation batch commits, before any WAL checkpoint that batch triggers. Returning an error stops at that durable boundary.

type ReconciliationStats ¶

type ReconciliationStats struct {
	Batches int        `json:"batches"`
	Writes  WriteStats `json:"writes"`
}

ReconciliationStats describes durable work completed during reconciliation.

type ReconciliationStatusRepository ¶

type ReconciliationStatusRepository interface {
	ReconciliationPending(context.Context) (bool, error)
}

ReconciliationStatusRepository is the optional, narrow capability used by indexing to prove that no resolver work remains. Absence of this capability is deliberately treated as unknown, never as clean.

type RelationDirection ¶

type RelationDirection string

RelationDirection selects which side of a subject node a bounded catalog evidence lookup follows.

const (
	IncomingRelations RelationDirection = "incoming"
	OutgoingRelations RelationDirection = "outgoing"
)

type RelationEdgePage ¶

type RelationEdgePage struct {
	Items     []HydratedRelationEdge
	Truncated bool
}

RelationEdgePage contains at most Limit edges per requested relation.

type RelationEdgeQuery ¶

type RelationEdgeQuery struct {
	SubjectID string
	Direction RelationDirection
	Relations []EdgeKind
	Limit     int
}

RelationEdgeQuery requests exact relations adjacent to one subject. Limit is applied independently to each distinct relation.

func (q RelationEdgeQuery) Validate() error

type RelationEdgeRepository ¶

type RelationEdgeRepository interface {
	RelationEdges(context.Context, RelationEdgeQuery) (RelationEdgePage, error)
}

RelationEdgeRepository is the bounded, relation-filtered evidence port used by catalogs. Traversal continues to use QueryRepository adjacency methods.

type Repository ¶

type Repository interface {
	IndexRepository
	QueryRepository
	StatusRepository
	Close() error
	Path() string
}

Repository is the complete port implemented by a storage adapter. Services accept the smaller interfaces above so their dependencies stay explicit.

type ScopedNode ¶

type ScopedNode struct {
	Repository string `json:"repository,omitempty"`
	Node       Node   `json:"node"`
}

ScopedNode pairs a node with the indexed repository that stores it.

type StatusRepository ¶

type StatusRepository interface {
	Meta(context.Context, string) (string, error)
	Counts(context.Context) (Counts, error)
}

StatusRepository exposes only metadata and aggregate counts.

type TopologyRepository ¶

type TopologyRepository interface {
	CatalogRepository
	QueryRepository
}

TopologyRepository adds traversal adjacency to the bounded catalog port. Catalog-only consumers do not inherit unbounded traversal methods.

type WriteBatchStats ¶

type WriteBatchStats struct {
	Batches int64 `json:"batches"`
	Rows    int64 `json:"rows"`
	Bytes   int64 `json:"bytes"`
}

WriteBatchStats describes bounded adapter writes without exposing a storage dialect or its configured limits to indexing callers.

type WriteStats ¶

type WriteStats struct {
	Nodes WriteBatchStats `json:"nodes"`
	Facts WriteBatchStats `json:"facts"`
	Edges WriteBatchStats `json:"edges"`
}

WriteStats reports rows and encoded payload bytes sent through bounded write batches. Adapters that do not batch writes may leave it empty.