cache

package
v0.1.4 Latest Latest
Warning

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

 Go to latest Published: Aug 8, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewOverlayFS 

func NewOverlayFS(delegate FileSource) *overlayFS

Types

type Cache 

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

Cache is the process-wide file store, backed by a FileSource (the disk in production, an in-memory tree in tests). Include paths are not global: each view resolves its own from its workspace folder's config at creation.

func New 

func New() *Cache

New returns a disk-backed cache.

func NewWithFS added in v0.1.4 

func NewWithFS(fs FileSource) *Cache

NewWithFS returns a cache backed by fs, for tests and embedding.

func (*Cache) ReadFile 

func (c *Cache) ReadFile(ctx context.Context, u uri.URI) (FileHandle, error)

ReadFile implements FileSource by delegating to the backing source.

func (*Cache) WalkFiles added in v0.1.4 

func (c *Cache) WalkFiles(ctx context.Context, root uri.URI, fn func(uri.URI) error) error

WalkFiles implements FileSource by delegating to the backing source.

type DiskFile 

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

A DiskFile is a file on the filesystem, or a failure to read one. It implements the source.FileHandle interface.

func (*DiskFile) Content 

func (h *DiskFile) Content() ([]byte, error)

func (*DiskFile) URI 

func (h *DiskFile) URI() uri.URI

func (*DiskFile) Version 

func (h *DiskFile) Version() int32

type FileChange 

type FileChange struct {
	URI     uri.URI
	Version int
	Content []byte
	From    FileChangeType
}

func FileChangeFromLSPDidChange 

func FileChangeFromLSPDidChange(params *protocol.DidChangeTextDocumentParams) []*FileChange

FileChangeFromLSPDidChange converts a didChange payload into file changes. The server advertises whole-document sync, so whole-document events map one-to-one; incremental (partial) events are a client protocol violation and are skipped.

func (*FileChange) FullContent 

func (f *FileChange) FullContent() []byte

type FileChangeType 

type FileChangeType string
const (
	FileChangeTypeInitialize FileChangeType = "Initialize"
	FileChangeTypeDidOpen    FileChangeType = "DidOpen"
	FileChangeTypeDidChange  FileChangeType = "DidChange"
	FileChangeTypeDidClose   FileChangeType = "DidClose"
)

type FileHandle 

type FileHandle interface {
	// URI is the URI for this file handle.
	// TODO(rfindley): this is not actually well-defined. In some cases, there
	// may be more than one URI that resolve to the same FileHandle. Which one is
	// this?
	URI() uri.URI
	// Version returns the file version, as defined by the LSP client.
	// For on-disk file handles, Version returns 0.
	Version() int32
	// Content returns the contents of a file.
	// If the file is not available, returns a nil slice and an error.
	Content() ([]byte, error)
}

A FileHandle represents the URI, content, and optional version of a file tracked by the LSP session.

File content may be provided by the file system or from an overlay for an open file with unsaved edits. A FileHandle may record an attempt to read a non-existent file, in which case Content returns an error.

type FileID 

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

A FileID uniquely identifies a file in the file system.

If GetFileID(name1) returns the same ID as GetFileID(name2), the two file names denote the same file. A FileID is comparable, and thus suitable for use as a map key.

func GetFileID 

func GetFileID(filename string) (FileID, time.Time, error)

GetFileID returns the file system's identifier for the file, and its modification time. Like os.Stat, it reads through symbolic links.

type FileIndex added in v0.1.2 

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

FileIndex is the per-file semantic index: the file's definitions, enum values, name references, and annotation names, extracted in a single AST walk and cached with the parse. A re-parse replaces the whole ParsedFile, so the index never goes stale.

The index answers "what does this file contain". Cross-file questions — "where is this name defined", "who references it" — belong to source.Index, which composes FileIndexes over the include graph.

func (*FileIndex) Defs added in v0.1.2 

func (x *FileIndex) Defs() map[string]syntax.Node

Defs returns the file's top-level definitions indexed by name: structs, unions, exceptions, enums, services, consts, and typedefs. The node's concrete type identifies the definition kind.

func (*FileIndex) EnumValues added in v0.1.2 

func (x *FileIndex) EnumValues() map[string]*syntax.Identifier

EnumValues returns the file's enum value names indexed by name.

func (*FileIndex) References added in v0.1.2 

func (x *FileIndex) References() []Reference

References returns every name reference in the file, in document order: field and signature type references, constant value identifiers, and service extends references.

type FileSource 

type FileSource interface {
	// ReadFile returns the FileHandle for a given URI, either by
	// reading the content of the file or by obtaining it from a cache.
	ReadFile(ctx context.Context, uri uri.URI) (FileHandle, error)
	// WalkFiles calls fn for every file under root, recursively, in
	// lexical order. The caller filters by kind (e.g. extension). An
	// error returned by fn stops the walk; per-entry failures (missing
	// roots, permissions) are the implementation's to skip or report.
	WalkFiles(ctx context.Context, root uri.URI, fn func(uri.URI) error) error
}

A FileSource maps URIs to FileHandles.

func NewMemFS added in v0.1.4 

func NewMemFS(files map[uri.URI][]byte) FileSource

NewMemFS returns a FileSource backed by files; nil is an empty tree.

type FilesMap 

type FilesMap = cowMap[uri.URI, FileHandle]

FilesMap holds the files of a snapshot.

func NewFilesMap added in v0.1.2 

func NewFilesMap() *FilesMap

NewFilesMap returns an empty files map.

type IncludeDeps added in v0.1.2 

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

IncludeDeps tracks, per file, its transitive include dependencies. It owns the IncludeGraph; callers never touch the underlying graph directly.

func NewIncludeDeps added in v0.1.2 

func NewIncludeDeps() *IncludeDeps

NewIncludeDeps returns an empty dependency set.

func (*IncludeDeps) Clone added in v0.1.2 

func (c *IncludeDeps) Clone() *IncludeDeps

Clone returns a deep copy, for snapshot copy-on-write.

func (*IncludeDeps) Dependents added in v0.1.2 

func (c *IncludeDeps) Dependents(file uri.URI) []uri.URI

Dependents returns every file that directly or transitively includes file, including file itself when it transitively includes itself. The result is sorted ascending by URI and cycle-safe.

func (*IncludeDeps) Forget added in v0.1.2 

func (c *IncludeDeps) Forget(file uri.URI) []uri.URI

Forget removes file's edges and returns its former dependents.

func (*IncludeDeps) Includers added in v0.1.2 

func (c *IncludeDeps) Includers(file uri.URI) []uri.URI

Includers returns the files that include file directly, in graph order.

func (*IncludeDeps) Includes added in v0.1.2 

func (c *IncludeDeps) Includes(file uri.URI) []uri.URI

Includes returns the files file includes directly, sorted ascending by URI.

func (*IncludeDeps) Register added in v0.1.2 

func (c *IncludeDeps) Register(file uri.URI, includes []*syntax.Include, resolve func(uri.URI, string) uri.URI) []uri.URI

Register replaces file's include edges, resolving them via resolve the same way snapshot parsing does. It returns the URIs whose dependency set changed: the union of file's old and new transitive dependents.

Duplicate includes resolve once; unknown include paths fall back to a relative path (see resolver.Resolve) and never crash.

type IncludeGraph 

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

IncludeGraph tracks include edges between files. Snapshots share the underlying mapper (Clone is O(1)); the first structural change after a clone deep-copies the graph, so edits that do not change include edges never pay for the copy.

func NewIncludeGraph 

func NewIncludeGraph() *IncludeGraph

func (*IncludeGraph) Clone 

func (g *IncludeGraph) Clone() *IncludeGraph

Clone returns a view sharing the same mapper. The clone and the original both become copy-on-write: the next structural change deep-copies.

func (*IncludeGraph) Get 

func (g *IncludeGraph) Get(file uri.URI) *IncludeNode

Get returns a copy of file's node. The graph's nodes are mutated in place by Set and removeWithoutLock, so a live node must never escape the lock.

func (*IncludeGraph) Remove 

func (g *IncludeGraph) Remove(file uri.URI)

func (*IncludeGraph) Set 

func (g *IncludeGraph) Set(file uri.URI, includes []*syntax.Include, resolve func(cur uri.URI, includePath string) uri.URI)

Set records the include edges of file. resolve maps an include path text to the URI of the included file (e.g. the snapshot's include resolver).

type IncludeNode 

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

func (*IncludeNode) Clone 

func (n *IncludeNode) Clone() *IncludeNode

func (*IncludeNode) InDegree 

func (n *IncludeNode) InDegree() []uri.URI

func (*IncludeNode) OutDegree 

func (n *IncludeNode) OutDegree() []uri.URI

type Overlay 

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

An Overlay is a file open in the editor. It may have unsaved edits. It implements the source.FileHandle interface.

func NewOverlay 

func NewOverlay(uri uri.URI, content []byte, version int32) *Overlay

func (*Overlay) Content 

func (o *Overlay) Content() ([]byte, error)

func (*Overlay) URI 

func (o *Overlay) URI() uri.URI

func (*Overlay) Version 

func (o *Overlay) Version() int32

type ParseCaches 

type ParseCaches = cowMap[uri.URI, *ParsedFile]

ParseCaches maps URIs to parsed files.

func NewParseCaches 

func NewParseCaches() *ParseCaches

NewParseCaches returns an empty parse cache.

type ParsedFile 

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

func Parse 

func Parse(fh FileHandle) (*ParsedFile, error)

Parse lexes and parses the file content into a ParsedFile.

func (*ParsedFile) AST 

func (p *ParsedFile) AST() *syntax.Document

func (*ParsedFile) AggregatedError 

func (p *ParsedFile) AggregatedError() error

func (*ParsedFile) Definitions 

func (p *ParsedFile) Definitions() map[string]syntax.Node

Definitions returns the file's top-level definitions indexed by name: structs, unions, exceptions, enums, services, consts, and typedefs. The node's concrete type identifies the definition kind.

func (*ParsedFile) EnumValues 

func (p *ParsedFile) EnumValues() map[string]*syntax.Identifier

EnumValues returns the file's enum value names indexed by name.

func (*ParsedFile) Errors 

func (p *ParsedFile) Errors() []syntax.Error

func (*ParsedFile) Index added in v0.1.2 

func (p *ParsedFile) Index() *FileIndex

Index returns the file's semantic index: definitions, enum values, name references, and annotation names from a single AST walk.

func (*ParsedFile) Mapper 

func (p *ParsedFile) Mapper() *mapper.Mapper

func (*ParsedFile) Tokens 

func (p *ParsedFile) Tokens() map[string]struct{}

Tokens returns the identifier tokens of the file, computed once and reused. A re-parse replaces the whole ParsedFile, so the cache never goes stale.

func (*ParsedFile) URI added in v0.1.2 

func (p *ParsedFile) URI() uri.URI

URI returns the URI of the parsed file.

type RefKind added in v0.1.2 

type RefKind uint8

RefKind classifies a name reference by the grammar slot it sits in. The slot decides what the reference can legally point at: an exception is only referenced from signatures, an enum value only from value positions. 

const (
	// RefFieldType is a type reference in a field-ish position: struct,
	// union, and exception fields, typedef targets, and const types.
	RefFieldType RefKind = iota + 1
	// RefSignatureType is a type reference in a service signature: a
	// function return type, argument, or throws member.
	RefSignatureType
	// RefConstValue is an identifier in a constant value position: a field
	// default or a const value, possibly qualified ("Color.RED").
	RefConstValue
	// RefServiceExtends is a service extends reference.
	RefServiceExtends
)

type Reference added in v0.1.2 

type Reference struct {
	Kind RefKind

	// Name is the reference text as written: "User", "shared.User", or
	// "shared.thrift.User".
	Name string

	// Node carries the reference's position: *syntax.Identifier for type
	// and service references, *syntax.ConstValue for value references.
	// Ranges come from the owning file's AST and mapper.
	Node syntax.Node
}

Reference is one name occurrence that resolves to a definition somewhere: in this file or in an included one. It is a raw fact — the name text as written, uninterpreted. Qualifier parsing ("shared.User" vs "shared.thrift.User") and definition matching live in the source layer, which knows the include graph.

type Resolver 

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

Resolver provides centralized include path resolution. It wraps the snapshot to provide a clean interface for resolving included files, types, and identifiers.

func NewResolver 

func NewResolver(ss *Snapshot) *Resolver

NewResolver creates a resolver for the given snapshot

func (*Resolver) GetIncludePath 

func (r *Resolver) GetIncludePath(ast *syntax.Document, includeName string) string

GetIncludePath returns the include path text for a given include name. Returns empty string if not found.

func (*Resolver) GetIncludeURI 

func (r *Resolver) GetIncludeURI(cur uri.URI, ast *syntax.Document, includeName string) uri.URI

GetIncludeURI returns the URI for an included file by include name. Returns empty URI if not found.

func (*Resolver) IncludePaths 

func (r *Resolver) IncludePaths() []string

IncludePaths returns the include paths configured for this snapshot

func (*Resolver) ResolveInclude 

func (r *Resolver) ResolveInclude(cur uri.URI, includePath string) uri.URI

ResolveInclude resolves an include path to a file URI. It first tries relative to the current file, then tries each include path.

type Session 

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

func NewSession 

func NewSession(cache *Cache) *Session

func (*Session) AddView 

func (s *Session) AddView(folder uri.URI, includePaths []string, config options.Patch) *View

AddView registers a view for the workspace folder, returning the existing view when the folder is already tracked. includePaths and config are the folder's resolved configuration; the view fixes them at creation.

func (Session) Forget 

func (fs Session) Forget(uri uri.URI)

Forget drops the overlay for uri, falling back to disk content.

func (Session) HasOverlay 

func (fs Session) HasOverlay(uri uri.URI) bool

HasOverlay reports whether uri has an open overlay.

func (Session) ReadFile 

func (fs Session) ReadFile(ctx context.Context, uri uri.URI) (FileHandle, error)

func (*Session) RemoveView 

func (s *Session) RemoveView(folder uri.URI)

RemoveView drops the view for the workspace folder and forgets every cached file-to-view mapping that pointed at it, so ViewOf re-resolves against the remaining folders.

func (Session) Update 

func (fs Session) Update(_ context.Context, changes []*FileChange) error

Update applies changes to the overlay set. DidClose changes remove the overlay; all other types create or replace it.

func (*Session) UpdateOverlayFS 

func (s *Session) UpdateOverlayFS(ctx context.Context, changes []*FileChange) error

func (*Session) ViewOf 

func (s *Session) ViewOf(fileURI uri.URI) (*View, error)

func (*Session) Views 

func (s *Session) Views() []*View

Views returns the workspace folders' views.

func (Session) WalkFiles added in v0.1.4 

func (fs Session) WalkFiles(ctx context.Context, root uri.URI, fn func(uri.URI) error) error

WalkFiles enumerates the delegate's tree, not the overlay: the walk discovers files on the underlying source, while open files are already known to the session via their didOpen.

type Snapshot 

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

func BuildSnapshotForTest 

func BuildSnapshotForTest(files []*FileChange) *Snapshot

func BuildSnapshotForTestWithPaths 

func BuildSnapshotForTestWithPaths(includePaths []string, files []*FileChange) *Snapshot

BuildSnapshotForTestWithPaths is BuildSnapshotForTest with configured include paths, for cross-project include resolution tests.

func NewSnapshot 

func NewSnapshot(view *View, includePaths []string) *Snapshot

func (*Snapshot) Acquire 

func (s *Snapshot) Acquire() func()

func (*Snapshot) Dependents 

func (s *Snapshot) Dependents(uri uri.URI) []uri.URI

Dependents returns the transitive dependents of uri: every file that directly or transitively includes it, in this snapshot.

func (*Snapshot) ForgetFile 

func (s *Snapshot) ForgetFile(uri uri.URI)

ForgetFile is called when file changed or removed. It removes file's include edges and drops the parse and file caches for file and every transitive dependent of file: their derived data is rebuilt lazily on the next request, while their content survives on disk (or in the overlay).

func (*Snapshot) Includers added in v0.1.2 

func (s *Snapshot) Includers(file uri.URI) []uri.URI

Includers returns the files that include file directly, in graph order.

func (*Snapshot) Includes added in v0.1.2 

func (s *Snapshot) Includes(file uri.URI) []uri.URI

Includes returns the files file includes directly, in include order.

func (*Snapshot) Parse 

func (s *Snapshot) Parse(ctx context.Context, uri uri.URI) (*ParsedFile, error)

func (*Snapshot) ReadFile 

func (s *Snapshot) ReadFile(ctx context.Context, uri uri.URI) (FileHandle, error)

func (*Snapshot) Resolver 

func (s *Snapshot) Resolver() *Resolver

Resolver returns a new Resolver instance for this snapshot. The resolver provides centralized include path resolution.

func (*Snapshot) TokensForFile 

func (s *Snapshot) TokensForFile(file uri.URI) map[string]struct{}

TokensForFile returns the identifier tokens of file and its transitively included files. Each file's token set is computed once per parse and reused, so typing does not re-walk the include closure's ASTs.

func (*Snapshot) View added in v0.1.2 

func (s *Snapshot) View() *View

View returns the view this snapshot serves: the workspace folder the snapshot resolves files under.

type View 

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

View is a rooted file tree with the configuration that applies to it. It is a god object; splitting the snapshot bookkeeping out remains a bigger redesign.

func NewView 

func NewView(folder uri.URI, fs FileSource, includePaths []string, config options.Patch) *View

func (*View) Config added in v0.1.4 

func (v *View) Config() options.Patch

Config returns the view's base configuration, without the client's workspace settings overlay.

func (*View) ContainsFile 

func (v *View) ContainsFile(uri uri.URI) bool

func (*View) FileChange 

func (v *View) FileChange(ctx context.Context, changes []*FileChange, postFns ...func(affected []uri.URI))

FileChange applies changes to the view: it swaps in a new snapshot (an O(1) copy-on-write clone) and re-parses the changed files, then runs the postFns asynchronously with the affected URIs (changed files plus their transitive dependents). The request thread never blocks on postFns, so diagnostics-heavy work (semantic analysis) does not stall the editor.

func (*View) FileKnown 

func (v *View) FileKnown(uri uri.URI) bool

func (*View) Folder 

func (v *View) Folder() uri.URI

Folder returns the workspace folder the view covers.

func (*View) IsCurrent 

func (v *View) IsCurrent(ss *Snapshot) bool

IsCurrent reports whether ss is the view's latest snapshot. Used by asynchronous work to drop results that a newer change superseded.

func (*View) KnownFiles 

func (v *View) KnownFiles() []uri.URI

KnownFiles returns the known file URIs of the view, sorted for deterministic iteration.

func (*View) MarkFileKnown 

func (v *View) MarkFileKnown(fileURI uri.URI)

func (*View) Snapshot 

func (v *View) Snapshot() (*Snapshot, func())

func (*View) WalkFiles added in v0.1.4 

func (v *View) WalkFiles(ctx context.Context, root uri.URI, fn func(uri.URI) error) error

WalkFiles enumerates the view's file source under root: the disk in production, the in-memory tree in tests.

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.