Module workspace_index 

Workspace indexing and refactoring orchestration. Core workspace-wide symbol index and lookup/query API. Workspace-wide symbol index for fast cross-file lookups in Perl LSP.

This module provides efficient indexing of symbols across an entire Perl workspace, enabling enterprise-grade features like find-references, rename refactoring, and workspace symbol search with ≤1ms response times.

LSP Workflow Integration

Core component in the Parse → Index → Navigate → Complete → Analyze pipeline:

1. Parse: AST generation from Perl source files
2. Index: Workspace symbol table construction with dual indexing strategy
3. Navigate: Cross-file symbol resolution and go-to-definition
4. Complete: Context-aware completion with workspace symbol awareness
5. Analyze: Cross-reference analysis and workspace refactoring operations

Performance Characteristics

• Symbol indexing: O(n) where n is total workspace symbols
• Symbol lookup: O(1) average with hash table indexing
• Cross-file queries: <50μs for typical workspace sizes
• Memory usage: ~1MB per 10K symbols with optimized storage
• Incremental updates: ≤1ms for file-level symbol changes
• Large workspace scaling: Designed to scale to 50K+ files and large codebases
• Benchmark targets: <50μs lookups and ≤1ms incremental updates at scale

Dual Indexing Strategy

Implements dual indexing for comprehensive Perl symbol resolution:

• Qualified names: Package::function for explicit references
• Bare names: function for context-dependent resolution
• 98% reference coverage: Handles both qualified and unqualified calls
• Automatic deduplication: Prevents duplicate results in queries

Usage Examples

use perl_workspace::workspace::workspace_index::WorkspaceIndex;
use url::Url;

let index = WorkspaceIndex::new();

// Index a Perl file
let uri = Url::parse("file:///example.pl")?;
let code = "package MyPackage;\nsub example { return 42; }";
index.index_file(uri, code.to_string())?;

// Find symbol definitions
let definition = index.find_definition("MyPackage::example");
assert!(definition.is_some());

// Workspace symbol search
let symbols = index.find_symbols("example");
assert!(!symbols.is_empty());

Related Modules

See also the symbol extraction, reference finding, and semantic token classification modules in the workspace index implementation.

Modules

lsp_adapter

LSP adapter for converting internal Location types to LSP types LSP adapter utilities for Navigate/Analyze workflows.

Structs

CrossFileReferenceQueryResult

Read-only cross-file query result used by rename/safe-delete planners.

EarlyExitRecord

Record describing the latest early-exit event.

FileFactShard

Write-through semantic fact storage for one indexed file.

FileIndex

File-level index data

IndexCoordinator

Coordinates index lifecycle, state transitions, and handler queries

IndexInstrumentationSnapshot

Snapshot of index lifecycle instrumentation.

IndexMetrics

Metrics for index lifecycle management and degradation detection.

IndexPerformanceCaps

Performance caps for workspace indexing operations.

IndexPhaseTransition

A phase transition while building the workspace index.

IndexResourceLimits

Configurable resource limits for workspace index.

IndexStateTransition

A state transition for index lifecycle instrumentation.

Location

Internal location type used during Navigate/Analyze workflows.

LspWorkspaceSymbol

LSP-compliant workspace symbol for wire format in Navigate/Analyze workflows.

ShardReplaceResult

Per-category incremental invalidation result.

SymbolIdentity

Stable symbol identity returned by cross-file reference queries.

SymbolKey

A normalized symbol key for cross-file lookups in Index/Navigate workflows.

SymbolReference

Reference to a symbol for Navigate/Analyze workflows.

WorkspaceIndex

Thread-safe workspace index

WorkspaceSymbol

A symbol in the workspace for Index/Navigate workflows.

Enums

DegradationReason

Reason for index degradation.

EarlyExitReason

Early-exit reasons for workspace indexing.

IndexPhase

Build phase while the index is in Building state.

IndexState

Index readiness state - explicit lifecycle management

IndexStateKind

Coarse index state kinds for instrumentation and transition tracking.

ReferenceKind

Classification of how a symbol is referenced in Navigate/Analyze workflows.

ResourceKind

Type of resource limit that was exceeded.

SymKind

Symbol kinds for cross-file indexing during Index/Navigate workflows.

SymbolKind

Unified Perl symbol classification for LSP tooling.

VarKind

Variable sigil classification for Perl’s three primary container types.

Functions

fs_path_to_uri

Convert a filesystem path to a file:// URI.

is_file_uri

Check if a URI uses the file:// scheme.

is_special_scheme

Check if a URI uses a special scheme (not file://).

normalize_var

Normalize a Perl variable name for Index/Analyze workflows.

uri_extension

Extract the file extension from a URI-like string.

uri_key

Normalize a URI to a consistent key for lookups.

uri_to_fs_path

Convert a file:// URI to a filesystem path.