Skip to content

Path Tree Caching

VukeFN edited this page Aug 13, 2026 · 2 revisions

Path Tree Caching

The extension builds a path tree cache of your project's Verse declarations for fast import resolution. This happens automatically in the background, and is what keeps Path Conversion fast in large projects.

Table of Contents


What Gets Cached

The cache scans all .verse files in your project and extracts:

  • Modules - ModuleName := module:
  • Classes - ClassName := class(parent):
  • Structs - StructName := struct:
  • Interfaces - InterfaceName := interface:
  • Enums - EnumName := enum: or enum<open>:
  • Functions - FunctionName(params)<effects>:
  • Extension Methods - (Type:type).MethodName(params):
  • Variables - VariableName : type

What Is Not Cached

A Verse block macro looks like a declaration to a line-by-line scan — if (Cond): has the same shape as a function, and array: the same shape as a variable. The scan rejects any line headed by one, so none of them reaches your import or completion candidates:

block loop if then else race rush sync branch defer spawn case for and or not option logic do array map assert let batch when first

Verse reserves every one of these, so none can name a declaration of yours and nothing real is lost by rejecting the line.


Supported Specifiers

The parser correctly handles all Verse specifiers:

Visibility specifiers:

  • <public>, <protected>, <private>, <internal>, <scoped>

Type specifiers:

  • <final>, <abstract>, <concrete>, <native>, <persistable>, <open>, <closed>

Effect specifiers:

  • <transacts>, <decides>, <suspends>, <computes>, <converges>

Multi-specifier declarations like MyClass<native><public> are fully supported.


Cache Storage

The cache is stored in VS Code's workspace storage (workspaceState) and persists across sessions. The cache includes:

  • All parsed identifiers with their full paths
  • Source file locations for each declaration
  • File index for quick lookups

Because storage is per workspace, each project keeps its own cache and they never mix.


Automatic Invalidation

File watchers automatically update the cache when:

  • A .verse file is modified
  • A .verse file is created
  • A .verse file is deleted

Changes are debounced (500ms by default) to avoid excessive updates during rapid saves.

Generated *.digest.verse files are deliberately ignored by these watchers — they are API surface rather than project declarations, and UEFN rewrites them often.


Settings

See Configuration for the full reference.

Setting Default Effect
cache.enableProjectCache true Whether the path tree is built and maintained at all
cache.autoRebuildOnStartup false Force a full rebuild when VS Code starts, instead of reusing the persisted cache
cache.watcherDebounceMs 500 How long to wait after a file change before updating (100-5000)

Manual Rebuild

Three commands cover the cache; all are Command Palette only, and none appear in the status bar menu. See Cache Management.

Command When to use it
Rebuild Project Path Cache Suggestions look outdated and you want a full rescan
Clear Project Path Cache The cache looks corrupt. Wipes the in-memory copy and the persisted one without rebuilding, so the next lookup starts cold
Show Cache Status Check module count, entry count and cache age

Cache Statistics

Run Verse Auto Imports: Show Cache Status from the Command Palette to see module count, entry count, and cache age.

For more detail, open the Output panel (Ctrl+Shift+U), select "Verse Auto Imports" from the dropdown, and look for cache-related entries. The "Verse Auto Imports - Debug" channel carries the full trace.

If the cache seems not to be updating at all, see Troubleshooting.

Clone this wiki locally