feat(perf): enhance performance by improving disk caching and applying other optimizations

[mikeleppane]

Summary

This PR implements a comprehensive performance improvement plan that dramatically reduces Language Server startup time and improves edit responsiveness.

• Reuse the executor for library loading instead of spawning new processes
• Cache resource LibraryDoc objects to .robotcode_cache/*/resource/
• Only invalidate namespaces that actually import the changed file
• Allow up to 4 concurrent library loads (max_workers=min(cpu_count, 4))
• O(1) lookup for documents importing a given source via reverse dependency map
• get_library_users() and get_variables_users() for instant change propagation
• Persist namespace initialization state to disk
• Skip full import resolution on warm starts

Testing Plan

• 28 unit tests for PickleDataCache atomic writes
• 20 unit tests for NamespaceMetaData and cached entries
• 15 unit tests for ResourceMetaData cache keys
• 11 integration tests for namespace caching behavior

Architecture

Architecture Overview

flowchart TB
    subgraph cache["Disk Cache (.robotcode_cache/)"]
        lib["libdoc/<br/>Library docs"]
        res["resource/<br/>Resource docs"]
        ns["namespace/<br/>Namespace state"]
    end

    subgraph perf["Performance Optimizations"]
        p1["Shared Process Pool"]
        p2["Resource Caching"]
        p3["Targeted Invalidation"]
        p4["Parallel Library Loading"]
        p5["O(1) Dependency Lookups"]
        p7["Namespace Caching"]
        p9["Atomic Writes"]
    end

    subgraph maps["Reverse Dependency Maps"]
        imp["_importers<br/>source → documents"]
        lu["_library_users<br/>lib → documents"]
        vu["_variables_users<br/>var → documents"]
    end

    p1 --> lib
    p2 --> res
    p7 --> ns
    p9 --> ns
    p3 --> imp
    p5 --> lu
    p5 --> vu

Loading

Cold vs Warm Start Flow

flowchart TB
    subgraph startup["IDE Startup"]
        open["User Opens VS Code"]
    end

    subgraph cold["Cold Start (No Cache) ~2-4 min"]
        c1["Parse .robot files"]
        c2["Resolve imports in parallel"]
        c3["Load libraries<br/>(shared executor)"]
        c4["Build namespaces"]
        c5["Save to cache<br/>(atomic write)"]
        c1 --> c2 --> c3 --> c4 --> c5
    end

    subgraph warm["Warm Start (Cache Hit) ~10-20 sec"]
        w1["Check .cache.pkl exists"]
        w2{"Validate:<br/>mtime + size?"}
        w3["Load (meta, spec)"]
        w4["Check environment identity"]
        w5["Restore namespace"]
        w1 --> w2
        w2 -->|"Match"| w3 --> w4 --> w5
        w2 -->|"Changed"| miss["Rebuild"]
    end

    subgraph runtime["Runtime Editing"]
        r1["File changed"]
        r2["O(1) lookup affected docs"]
        r3["Targeted invalidation"]
        r4["Rebuild only affected"]
        r1 --> r2 --> r3 --> r4
    end

    open --> cold
    open --> warm
    
    style cold fill:#ffcccc,stroke:#cc0000
    style warm fill:#ccffcc,stroke:#00cc00
    style runtime fill:#cce5ff,stroke:#0066cc

Loading

Cache Validation Chain

sequenceDiagram
    participant LS as Language Server
    participant Cache as Disk Cache
    participant FS as File System

    Note over LS,FS: Warm Start Validation
    
    LS->>Cache: Load .cache.pkl
    Cache-->>LS: (meta, spec) tuple
    
    LS->>FS: stat(source_file)
    FS-->>LS: mtime, size
    
    alt mtime matches
        alt size matches
            Note over LS: Skip content hash!<br/>(Fast path)
            LS->>LS: Check python_executable
            LS->>LS: Check sys_path_hash
            alt Environment matches
                LS->>LS: Restore from cache ✓
            else Environment changed
                LS->>LS: Rebuild namespace
            end
        else size differs
            LS->>FS: Read first+last 64KB
            FS-->>LS: content chunks
            LS->>LS: Compute tiered hash
            alt Hash matches
                LS->>LS: Restore from cache ✓
            else Hash differs
                LS->>LS: Rebuild namespace
            end
        end
    else mtime differs
        LS->>LS: Rebuild namespace
    end

Loading