Struct WorkspaceIndex

Source

pub struct WorkspaceIndex { /* private fields */ }

Expand description

Workspace indexing and refactoring orchestration. Thread-safe workspace index

Implementations§

Source §

impl WorkspaceIndex

Source

pub fn new() -> WorkspaceIndex

Create a new empty index

§Returns

A workspace index with empty file and symbol tables.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
assert!(!index.has_symbols());

Source

pub fn with_capacity( estimated_files: usize, avg_symbols_per_file: usize, ) -> WorkspaceIndex

Create a workspace index with pre-allocated capacity.

Pre-allocating reduces the number of rehash operations during large-workspace startup. Use this instead of new() when the approximate workspace size is known in advance (e.g. from a file discovery scan).

§Arguments

estimated_files - Expected number of source files in the workspace.
avg_symbols_per_file - Expected average number of symbols per file.

§Panics

Does not panic. Overflow is prevented via saturating_mul and an upper cap on the symbol/reference map capacity.

§Examples

use perl_workspace::workspace::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::with_capacity(1000, 20);
assert!(!index.has_symbols());

Source

pub fn set_workspace_folders(&self, folders: Vec<String>)

Set the workspace folder URIs for multi-root workspace support.

This method updates the list of workspace folders that the index uses to determine folder attribution for files and symbols.

§Arguments

folders - A vector of workspace folder URIs

§Examples

use perl_workspace::workspace::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
index.set_workspace_folders(vec![
    "file:///project1".to_string(),
    "file:///project2".to_string(),
]);

Source

pub fn workspace_folders(&self) -> Vec<String>

Get the current workspace folder URIs.

§Returns

A vector of workspace folder URIs.

Source

pub fn index_file(&self, uri: Url, text: String) -> Result<(), String>

Index a file from its URI and text content

§Arguments

uri - File URI identifying the document
text - Full Perl source text for indexing

§Returns

Ok(()) when indexing succeeds, or an error message otherwise.

§Errors

Returns an error if parsing fails or the document store cannot be updated.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;
use url::Url;

let index = WorkspaceIndex::new();
let uri = Url::parse("file:///example.pl")?;
index.index_file(uri, "sub hello { return 1; }".to_string())?;

Returns: Ok(()) when indexing succeeds, otherwise an error string.

Source

pub fn remove_file(&self, uri: &str)

Remove a file from the index

§Arguments

uri - File URI (string form) to remove

§Returns

Nothing. The index is updated in-place.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
index.remove_file("file:///example.pl");

Source

pub fn remove_file_url(&self, uri: &Url)

Remove a file from the index (URL variant for compatibility)

§Arguments

uri - File URI as a parsed Url

§Returns

Nothing. The index is updated in-place.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;
use url::Url;

let index = WorkspaceIndex::new();
let uri = Url::parse("file:///example.pl")?;
index.remove_file_url(&uri);

Source

pub fn clear_file(&self, uri: &str)

Clear a file from the index (alias for remove_file)

§Arguments

uri - File URI (string form) to remove

§Returns

Nothing. The index is updated in-place.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
index.clear_file("file:///example.pl");

Source

pub fn clear_file_url(&self, uri: &Url)

Clear a file from the index (URL variant for compatibility)

§Arguments

uri - File URI as a parsed Url

§Returns

Nothing. The index is updated in-place.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;
use url::Url;

let index = WorkspaceIndex::new();
let uri = Url::parse("file:///example.pl")?;
index.clear_file_url(&uri);

Source

pub fn remove_folder(&self, folder_uri: &str)

Remove all files from a specific workspace folder.

This method removes all indexed files that belong to the given workspace folder URI. This is useful when a workspace folder is removed from the multi-root workspace.

§Arguments

folder_uri - The workspace folder URI to remove files from

§Examples

use perl_workspace::workspace::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
// Index files from multiple folders...
index.remove_folder("file:///project1");

Source

pub fn index_file_str(&self, uri: &str, text: &str) -> Result<(), String>

Index a file from a URI string for the Index/Analyze workflow.

Accepts either a file:// URI or a filesystem path. Not available on wasm32 targets (requires filesystem path conversion).

§Arguments

uri - File URI string or filesystem path.
text - Full Perl source text for indexing.

§Returns

Ok(()) when indexing succeeds, or an error message otherwise.

§Errors

Returns an error if the URI is invalid or parsing fails.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
index.index_file_str("file:///example.pl", "sub hello { }")?;

Source

pub fn index_files_batch( &self, files_to_index: Vec<(Url, String)>, ) -> Vec<String>

Index multiple files in a single batch operation.

This is significantly faster than calling index_file in a loop for initial workspace scans because it defers the global symbol cache rebuild to a single pass at the end.

Phase 1: Parse all files without holding locks. Phase 2: Bulk-insert file indices and rebuild the symbol cache once.

Source

pub fn find_references(&self, symbol_name: &str) -> Vec<Location>

Find all references to a symbol using dual indexing strategy

This function searches for both exact matches and bare name matches when the symbol is qualified. For example, when searching for “Utils::process_data”:

First searches for exact “Utils::process_data” references
Then searches for bare “process_data” references that might refer to the same function

This dual approach handles cases where functions are called both as:

Qualified: Utils::process_data()
Unqualified: process_data() (when in the same package or imported)

§Arguments

symbol_name - Symbol name or qualified name to search

§Returns

All reference locations found for the requested symbol.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
let _refs = index.find_references("Utils::process_data");

Source

pub fn query_symbol_references( &self, symbol_name: &str, ) -> Option<CrossFileReferenceQueryResult>

Resolve a symbol and return its definition/reference set for cross-file planning.

Returns None when no definition can be resolved for symbol_name.

Source

pub fn count_usages(&self, symbol_name: &str) -> usize

Count non-definition references (usages) of a symbol.

Like find_references but excludes ReferenceKind::Definition entries, returning only actual usage sites. This is used by code lens to show “N references” where N means call sites, not the definition itself.

Source

pub fn find_definition(&self, symbol_name: &str) -> Option<Location>

Find the definition of a symbol

§Arguments

symbol_name - Symbol name or qualified name to resolve

§Returns

The first matching definition location, if found.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
let _def = index.find_definition("MyPackage::example");

Source

pub fn all_symbols(&self) -> Vec<WorkspaceSymbol>

Get all symbols in the workspace

§Returns

A vector containing every symbol currently indexed.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
let _symbols = index.all_symbols();

Source

pub fn clear(&self)

Clear all indexed files and symbols from the workspace.

Source

pub fn replace_fact_shard_incremental( &self, key: &str, new_shard: FileFactShard, ) -> ShardReplaceResult

Replace a FileFactShard with per-category incremental invalidation.

Compares the whole-file content_hash first; when unchanged the replacement is skipped entirely. Otherwise each per-category hash (anchors_hash, entities_hash, occurrences_hash, edges_hash) is compared individually. Only categories whose hash changed trigger removal of old entries and insertion of new ones in the cross-file semantic indexes.

Validates: Requirements 18.1, 18.2, 18.3, 18.4, 18.5

Source

pub fn fact_shard_count(&self) -> usize

Number of stored file fact shards.

Source

pub fn file_fact_shard(&self, uri: &str) -> Option<FileFactShard>

Fetch a file fact shard for test/inspection.

Source

pub fn file_count(&self) -> usize

Return the number of indexed files in the workspace

Source

pub fn symbol_count(&self) -> usize

Return the total number of symbols across all indexed files

Source

pub fn files_in_folder(&self, folder_uri: &str) -> Vec<FileIndex>

Get all files in a specific workspace folder

§Arguments

folder_uri - Workspace folder URI to filter by

§Returns

A vector of file indices belonging to the specified folder

Source

pub fn symbols_in_folder(&self, folder_uri: &str) -> Vec<WorkspaceSymbol>

Get all symbols in a specific workspace folder

§Arguments

folder_uri - Workspace folder URI to filter by

§Returns

A vector of symbols belonging to the specified folder

Source

pub fn has_symbols(&self) -> bool

Check if the workspace index has symbols (soft readiness check)

Returns true if the index contains any symbols, indicating that at least some files have been indexed and the workspace is ready for symbol-based operations like completion.

§Returns

true if any symbols are indexed, otherwise false.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
assert!(!index.has_symbols());

Source

pub fn search_symbols(&self, query: &str) -> Vec<WorkspaceSymbol>

Search for symbols by query

§Arguments

query - Substring to match against symbol names

§Returns

Symbols whose names or qualified names contain the query string.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
let _results = index.search_symbols("example");

Source

pub fn find_symbols(&self, query: &str) -> Vec<WorkspaceSymbol>

Find symbols by query (alias for search_symbols for compatibility)

§Arguments

query - Substring to match against symbol names

§Returns

Symbols whose names or qualified names contain the query string.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
let _results = index.find_symbols("example");

Source

pub fn rank_symbols_by_folder( &self, symbols: Vec<WorkspaceSymbol>, doc_uri: &str, ) -> Vec<WorkspaceSymbol>

Rank symbols by folder proximity to a document

Returns symbols sorted by: same folder > other folders

§Arguments

symbols - Symbols to rank
doc_uri - Document URI to determine folder context

§Returns

Symbols ranked by folder proximity (same folder first)

§Examples

use perl_parser::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
let symbols = index.search_symbols("example");
let ranked = index.rank_symbols_by_folder(symbols, "file:///project1/src/main.pl");

Source

pub fn search_symbols_ranked( &self, name: &str, doc_uri: &str, ) -> Vec<WorkspaceSymbol>

Search for symbols with folder-aware ranking

Combines symbol search with folder proximity ranking

§Arguments

name - Symbol name to search for
doc_uri - Document URI for ranking context

§Returns

Ranked symbols with same-folder results first

§Examples

use perl_parser::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
let ranked = index.search_symbols_ranked("example", "file:///project1/src/main.pl");

Source

pub fn same_package( &self, symbol_a: &WorkspaceSymbol, symbol_b: &WorkspaceSymbol, ) -> bool

Determine if two symbols are in the same package

§Arguments

symbol_a - First symbol
symbol_b - Second symbol

§Returns

true if both symbols are in the same package

Source

pub fn same_package_by_container( &self, package_a: &str, package_b: &str, ) -> bool

Determine if two package names are the same (helper for testing)

§Arguments

package_a - First package name
package_b - Second package name

§Returns

true if both package names are equal

Source

pub fn extract_package_name(&self, symbol_name: &str) -> Option<String>

Extract package name from a symbol name

§Arguments

symbol_name - Symbol name (e.g., “Foo::Bar::baz” or “baz”)

§Returns

Package name (e.g., “Foo::Bar”) or None for main package

Source

pub fn file_symbols(&self, uri: &str) -> Vec<WorkspaceSymbol>

Get symbols in a specific file

§Arguments

uri - File URI to inspect

§Returns

All symbols indexed for the requested file.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
let _symbols = index.file_symbols("file:///example.pl");

Source

pub fn file_dependencies(&self, uri: &str) -> HashSet<String>

Get dependencies of a file

§Arguments

uri - File URI to inspect

§Returns

A set of module names imported by the file.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
let _deps = index.file_dependencies("file:///example.pl");

Source

pub fn find_dependents(&self, module_name: &str) -> Vec<String>

Find all files that depend on a module

§Arguments

module_name - Module name to search for in file dependencies

§Returns

A list of file URIs that import or depend on the module.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
let _files = index.find_dependents("My::Module");

Source

pub fn document_store(&self) -> &DocumentStore

Get the document store

§Returns

A reference to the in-memory document store.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
let _store = index.document_store();

Source

pub fn find_unused_symbols(&self) -> Vec<WorkspaceSymbol>

Find unused symbols in the workspace

§Returns

Symbols that have no non-definition references in the workspace.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
let _unused = index.find_unused_symbols();

Source

pub fn get_package_members(&self, package_name: &str) -> Vec<WorkspaceSymbol>

Get all symbols that belong to a specific package

§Arguments

package_name - Package name to match (e.g., My::Package)

§Returns

Symbols defined within the requested package.

§Examples

use perl_parser::workspace_index::WorkspaceIndex;

let index = WorkspaceIndex::new();
let _members = index.get_package_members("My::Package");

Source

pub fn find_def(&self, key: &SymbolKey) -> Option<Location>

Find the definition location for a symbol key during Index/Navigate stages.

§Arguments

key - Normalized symbol key to resolve.

§Returns

The definition location for the symbol, if found.

§Examples

use perl_parser::workspace_index::{SymKind, SymbolKey, WorkspaceIndex};
use std::sync::Arc;

let index = WorkspaceIndex::new();
let key = SymbolKey { pkg: Arc::from("My::Package"), name: Arc::from("example"), sigil: None, kind: SymKind::Sub };
let _def = index.find_def(&key);

Source

pub fn find_refs(&self, key: &SymbolKey) -> Vec<Location>

Find reference locations for a symbol key using dual indexing.

Searches both qualified and bare names to support Navigate/Analyze workflows.

§Arguments

key - Normalized symbol key to search for.

§Returns

All reference locations for the symbol, excluding the definition.

§Examples

use perl_parser::workspace_index::{SymKind, SymbolKey, WorkspaceIndex};
use std::sync::Arc;

let index = WorkspaceIndex::new();
let key = SymbolKey { pkg: Arc::from("main"), name: Arc::from("example"), sigil: None, kind: SymKind::Sub };
let _refs = index.find_refs(&key);