parser

type Builder ¶

type Builder struct {
	Input    Input
	Language string
	Result   graph.ParseResult
	// contains filtered or unexported fields
}

func NewBuilder(input Input, language string) *Builder

func (b *Builder) AddFact(from string, kind graph.EdgeKind, targetID, target string, targetKind graph.NodeKind, loc graph.Location, properties map[string]string)

func (b *Builder) AddNamedSourceFact(source string, sourceKind graph.NodeKind, kind graph.EdgeKind, targetID, target string, targetKind graph.NodeKind, loc graph.Location, properties map[string]string)

func (b *Builder) AddNode(node graph.Node) string

func (b *Builder) Declare(parent string, node graph.Node) string

func (b *Builder) Diagnostic(line int, level, message string)

func (b *Builder) FileID() string

func (b *Builder) Finish() graph.ParseResult

type Input ¶

type Input struct {
	Root    string
	Path    string
	Content []byte
	// SourcePaths is the authoritative repository-relative source membership
	// for this indexing run. A nil slice means the caller has no membership
	// snapshot and repository-wide parsers must use their deterministic fallback.
	SourcePaths []string
	Repository  string
	RepoID      string
	GoModule    string
	SemanticKey string
	// ScopeKey is the scope-local component of this file's semantic key, when
	// the caller has already derived it. A parser that would otherwise compute
	// the same value again consumes this instead. Empty means the caller has no
	// value to offer and the parser derives its own, so a missing key is never
	// read as a match.
	ScopeKey string
}

type Parser ¶

type Parser interface {
	Language() string
	Supports(path string) bool
	Parse(context.Context, Input) (graph.ParseResult, error)
}

type Registry ¶

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

func NewRegistry(parsers ...Parser) *Registry

func (r *Registry) For(path string) (Parser, bool)

func (r *Registry) IsSemanticDependency(path string) bool

func (r *Registry) Languages() []string

func (r *Registry) SemanticAffectedPaths(root string, paths, changed []string) []string

func (r *Registry) SemanticLoadMetrics() map[string]SemanticLoadMetrics

func (r *Registry) WorkspaceSemanticEvidenceKeys(ctx context.Context, input Input) (map[string]string, bool, error)

func (r *Registry) WorkspaceSemanticKeys(ctx context.Context, input Input) (map[string]string, error)

type ScopeKeyer ¶ added in v0.2.3

type ScopeKeyer interface {
	ScopeKey(context.Context, Input) (string, error)
}

ScopeKeyer reports the scope-local component of a file's semantic key on its own. Deriving that component can cost filesystem work, and SemanticKey folds it into a larger string the caller cannot take apart, so a caller that needs the component itself asks for it here and hands it back through Input.ScopeKey rather than making the parser derive it twice.

type SemanticChangeProvider ¶

type SemanticChangeProvider interface {
	SemanticAffectedPaths(root string, allPaths, changedPaths []string) []string
}

SemanticChangeProvider expands incremental invalidation when a source or configuration edit can change otherwise untouched parser output. Root is the repository root the paths are relative to, so a provider that keeps a per-repository model can look up the right one rather than guess.

type SemanticDependencyProvider ¶

type SemanticDependencyProvider interface {
	SemanticDependencies() []string
}

SemanticDependencyProvider identifies repository files whose changes can alter this parser's output for otherwise unchanged source files.

type SemanticInputProvider ¶

type SemanticInputProvider interface {
	IsSemanticInput(string) bool
}

SemanticInputProvider recognizes repository files that contribute to a parser's semantic model without necessarily being parsed as graph sources. It covers dynamic dependency names that cannot be expressed as a fixed list.

type SemanticKeyer ¶

type SemanticKeyer interface {
	SemanticKey(context.Context, Input) (string, error)
}

SemanticKeyer lets a parser add repository-level configuration to a file's incremental cache key. Parsers that do not depend on such configuration do not need to implement it.

A parser that also implements WorkspaceSemanticKeyer refines that shared key here with the scope-local facts that change how this one file extracts. Callers pass the already computed workspace key as Input.SemanticKey so the repository-wide part is never recomputed per file.

type SemanticLoadMetrics ¶ added in v0.2.3

type SemanticLoadMetrics struct {
	// Loads counts whole-workspace loads, CacheHits the views served from the
	// in-process cache without one.
	Loads     int64 `json:"loads"`
	CacheHits int64 `json:"cache_hits"`
	// PersistedHits counts workspace entries adopted from the cross-process
	// view cache, and PersistedSaves the entries written to it.
	PersistedHits  int64 `json:"persisted_hits"`
	PersistedSaves int64 `json:"persisted_saves"`
	// PersistedDecodes counts the package segments decoded from an adopted
	// entry, and PersistedSegmentWrites the segments re-encoded by a save.
	PersistedDecodes       int64 `json:"persisted_decodes"`
	PersistedSegmentWrites int64 `json:"persisted_segment_writes"`
	// PeakConcurrent and LastDurationMS are observations rather than totals:
	// the highest concurrency seen and the duration of the most recent load.
	// Since leaves them as observed, so in a per-run report they describe the
	// loader's whole lifetime.
	PeakConcurrent int64 `json:"peak_concurrent"`
	LastDurationMS int64 `json:"last_duration_ms"`
	// LoadNS is the time spent in whole-workspace loads and DerivationNS the
	// part of it spent deriving views from what was loaded. DerivationNS is a
	// subset of LoadNS.
	LoadNS       int64 `json:"load_ns"`
	DerivationNS int64 `json:"derivation_ns"`
}

SemanticLoadMetrics reports a semantic loader's own counters for one process. They exist so a refresh can be attributed without a bespoke build: the whole-workspace load and the per-package view derivation both happen inside a single Parse call, so without these they are indistinguishable from per-file parse time.

The counters are reporting-only. Nothing may branch on them, and a loader that does not keep them reports zeroes rather than failing a run.

func (m SemanticLoadMetrics) Since(baseline SemanticLoadMetrics) SemanticLoadMetrics

type SemanticLoadMetricsReporter ¶ added in v0.2.3

type SemanticLoadMetricsReporter interface {
	SemanticLoadMetrics() SemanticLoadMetrics
}

SemanticLoadMetricsReporter is a parser that keeps the counters above. The indexer reports what it finds here and never recounts.

type WorkspaceSemanticEvidenceKeyer ¶

type WorkspaceSemanticEvidenceKeyer interface {
	WorkspaceSemanticEvidenceKey(context.Context, Input) (string, error)
}

WorkspaceSemanticEvidenceKeyer provides cheap evidence for semantic inputs outside the repository snapshot. When every workspace keyer implements it, callers may reuse a previously computed workspace key while Git proves all in-repository inputs unchanged and these evidence keys still match.

type WorkspaceSemanticKeyer ¶

type WorkspaceSemanticKeyer interface {
	WorkspaceSemanticKey(context.Context, Input) (string, error)
}

WorkspaceSemanticKeyer marks a semantic key that is shared by every source file in one indexing run, allowing the indexer to compute it once.