Struct SymbolReferences 

pub struct SymbolReferences { /* private fields */ }

Stores various maps tracking references between symbols (classes, functions, etc.) and class-like members (methods, properties, constants, etc.) within the codebase.

This is primarily used for dependency analysis, understanding code structure, and potentially for tasks like dead code detection or impact analysis.

Implementations

impl SymbolReferences

pub fn new() -> Self

Creates a new, empty SymbolReferences collection.

pub fn is_empty(&self) -> bool

Returns whether no references of any kind are recorded.

pub fn count_body_references(&self) -> usize

Counts the total number of body references from symbols and files.

pub fn count_signature_references(&self) -> usize

Counts the total number of signature references from symbols and files.

pub fn total_map_entries(&self) -> usize

Returns the total number of map entries (keys) across all reference maps. Useful for memory auditing — this count should remain stable across cycles in a long-running process.

pub fn count_referencing_symbols( &self, symbol: &SymbolIdentifier, in_signature: bool, ) -> usize

Counts how many symbols reference the given symbol.

Arguments

• symbol - The symbol to check references to
• in_signature - If true, count signature references; if false, count body references

Returns

The number of symbols that reference the given symbol

pub fn count_property_reads(&self, property: &SymbolIdentifier) -> usize

Counts how many symbols have a read reference to the given property.

Arguments

• property - The property symbol identifier (ClassName, PropertyName) to check

Returns

The number of symbols that read the given property

pub fn count_property_writes(&self, property: &SymbolIdentifier) -> usize

Counts how many symbols have a write reference to the given property.

Arguments

• property - The property symbol identifier (ClassName, PropertyName) to check

Returns

The number of symbols that write to the given property

pub fn add_symbol_reference_to_class_member( &mut self, referencing_symbol: Word, class_member: SymbolIdentifier, in_signature: bool, )

Records that a top-level symbol (e.g., a function) references a class member.

Automatically adds a reference from the referencing symbol to the member’s class.

Arguments

• referencing_symbol: The FQN of the function or global const making the reference.
• class_member: A tuple (ClassName, MemberName) being referenced.
• in_signature: true if the reference occurs in a signature context, false if in the body.

pub fn add_symbol_reference_to_symbol( &mut self, referencing_symbol: Word, symbol: Word, in_signature: bool, )

Records that a top-level symbol references another top-level symbol.

Skips self-references. Skips body references if already referenced in signature.

Arguments

• referencing_symbol: The FQN of the symbol making the reference.
• symbol: The FQN of the symbol being referenced.
• in_signature: true if the reference occurs in a signature context, false if in the body.

pub fn add_symbol_reference( &mut self, referencing: SymbolIdentifier, referenced: SymbolIdentifier, in_signature: bool, )

Records a reference between arbitrary top-level symbols or class-like members.

pub fn add_reference( &mut self, referencing: ReferenceOrigin, referenced: SymbolIdentifier, in_signature: bool, )

Records a body or signature reference from a symbol/member or file origin.

pub fn add_property_read_reference( &mut self, referencing: ReferenceOrigin, property: SymbolIdentifier, )

Records a property read from an explicit symbol, member, or file source.

pub fn add_property_write_reference( &mut self, referencing: ReferenceOrigin, property: SymbolIdentifier, )

Records a property write from an explicit symbol, member, or file source.

pub fn add_overridden_member_reference( &mut self, referencing: SymbolIdentifier, overridden: SymbolIdentifier, )

Records an explicit reference to an overridden class-like member.

pub fn add_functionlike_return_reference( &mut self, referencing: SymbolIdentifier, referenced: SymbolIdentifier, )

Records an explicit use of another function-like’s return value.

pub fn add_class_member_reference_to_class_member( &mut self, referencing_class_member: SymbolIdentifier, class_member: SymbolIdentifier, in_signature: bool, )

Records that a class member references another class member.

Automatically adds references from the referencing member’s class to the referenced member’s class, and from the referencing member to the referenced member’s class. Skips self-references.

Arguments

• referencing_class_member: Tuple (ClassName, MemberName) making the reference.
• class_member: Tuple (ClassName, MemberName) being referenced.
• in_signature: true if the reference occurs in a signature context, false if in the body.

pub fn add_class_member_reference_to_symbol( &mut self, referencing_class_member: SymbolIdentifier, symbol: Word, in_signature: bool, )

Records that a class member references a top-level symbol.

Automatically adds a reference from the referencing member’s class to the referenced symbol. Skips references to the member’s own class. Skips body references if already referenced in signature.

Arguments

• referencing_class_member: Tuple (ClassName, MemberName) making the reference.
• symbol: The FQN of the symbol being referenced.
• in_signature: true if the reference occurs in a signature context, false if in the body.

pub fn add_file_reference_to_class_member( &mut self, file_name: Word, class_member: SymbolIdentifier, in_signature: bool, )

Adds a file-level reference to a symbol or class-like member.

Member references also imply a reference to their containing class-like symbol.

pub fn add_reference_to_class_member( &mut self, scope: &ScopeContext<'_>, class_member: SymbolIdentifier, in_signature: bool, )

Convenience method to add a reference from the current function context to a class member. Delegates to appropriate add_* methods based on the function context.

pub fn add_reference_for_method_call( &mut self, scope: &ScopeContext<'_>, method: &MethodIdentifier, )

pub fn add_reference_for_property_read( &mut self, scope: &ScopeContext<'_>, class_name: Word, property_name: Word, )

Records a read reference to a property (e.g., $this->prop used as a value).

pub fn add_reference_for_property_write( &mut self, scope: &ScopeContext<'_>, class_name: Word, property_name: Word, )

Records a write reference to a property (e.g., $this->prop = value). This is tracked separately from read references to enable write-only property detection.

pub fn add_reference_to_overridden_class_member( &mut self, scope: &ScopeContext<'_>, class_member: SymbolIdentifier, )

Convenience method to add a reference from the current function context to an overridden class member (e.g., parent::foo). Delegates based on the function context.

pub fn add_reference_to_symbol( &mut self, scope: &ScopeContext<'_>, symbol: Word, in_signature: bool, )

Convenience method to add a reference from the current function context to a top-level symbol. Delegates to appropriate add_* methods based on the function context.

pub fn add_reference_to_functionlike_return( &mut self, referencing_functionlike: FunctionLikeIdentifier, referenced_functionlike: FunctionLikeIdentifier, )

Records that one function/method references the return value of another. Used for dead code analysis.

pub fn extend(&mut self, other: Self)

Merges references from another SymbolReferences instance into this one. Existing references are extended, not replaced.

pub fn for_each_reference( &self, visit: impl FnMut(ReferenceOrigin, SymbolIdentifier, SymbolReferenceKind), )

Visits every recorded reference without materializing a copy of the graph.

pub fn get_references_to_symbol( &self, target_symbol: SymbolIdentifier, ) -> HashSet<&SymbolIdentifier>

Finds all symbols/members that reference a specific target symbol/member. Checks both body and signature references.

Arguments

• target_symbol: The (SymbolName, MemberName) tuple being referenced.

Returns

A HashSet containing &(RefSymbol, RefMember) tuples of all items referencing the target.

pub fn has_file_reference_to_symbol( &self, target_symbol: SymbolIdentifier, ) -> bool

Returns whether a body or signature reference to a symbol originates from top-level file code.

pub fn get_invalid_symbols( &self, codebase_diff: &CodebaseDiff, ) -> Option<(HashSet<SymbolIdentifier>, WordSet, WordSet)>

Calculates sets of invalid symbols and members based on detected code changes (CodebaseDiff). Propagates invalidation through the dependency graph stored in signature references. Limits propagation expense to avoid excessive computation on large changes.

Arguments

• codebase_diff: Information about added, deleted, or modified symbols/signatures.

Returns

Some((invalid_signatures, partially_invalid, invalid_files)) on success, where invalid_signatures contains all symbol/member pairs whose signature is invalid (including propagated ones), and partially_invalid contains symbols with at least one invalid member. invalid_files contains logical file names whose top-level code references a symbol with an invalid signature. Returns None if the propagation exceeds an expense limit (currently 5000 steps).

pub fn restore_references_for_safe_symbols( &mut self, previous: &SymbolReferences, safe_symbols: &WordSet, safe_symbol_members: &HashSet<SymbolIdentifier>, )

Extracts references originating from safe (skipped) symbols and merges them into this instance.

When incremental analysis runs with diff = true, the analyzer skips safe symbols, which means their body references are not collected. This method copies those missing references from the previous run’s reference graph.

Only references from symbols that are in safe_symbols or safe_symbol_members (and not already present in this instance) are copied.

Arguments

• previous - The previous run’s complete symbol references
• safe_symbols - Set of safe top-level symbol names
• safe_symbol_members - Set of safe (symbol, member) pairs

pub fn remove_body_references_for_symbols( &mut self, symbols_and_members: &HashSet<SymbolIdentifier>, file_names: &[Word], )

Removes body references originating from the given symbols/members.

Used by the body-only fast path: when only function/method bodies changed (no signature changes), we remove old body references and let the analyzer rebuild them fresh. Signature references are kept because signatures didn’t change.

Also removes function-like return references and property read/write references from the given symbols, as those originate from body code.

File-level references keyed by the given file names are also removed.

pub fn remove_references_from_files(&mut self, file_names: &WordSet)

Removes every reference originating from the given files.

Used when files are fully reanalyzed after a signature change. Both body and signature references must be rebuilt because either may have changed.

pub fn retain_references_from_files(&mut self, file_names: &WordSet)

Removes references whose source files no longer exist in the current codebase.

pub fn remove_references_from_invalid_symbols( &mut self, invalid_symbols_and_members: &HashSet<SymbolIdentifier>, )

Removes all references originating from symbols/members that are marked as invalid.

Arguments

• invalid_symbols_and_members: A set containing (SymbolName, MemberName) tuples for invalid items.

pub fn retain_safe_symbol_references( &mut self, safe_symbols: &WordSet, safe_symbol_members: &HashSet<SymbolIdentifier>, )

Retains only references originating from safe (unchanged) symbols, removing all others.

This is the inverse of [remove_references_from_invalid_symbols]: instead of specifying what to remove, you specify what to keep. References from non-safe symbols will be rebuilt by populate_codebase and the analyzer.

This method also retains all builtin/prelude references (those where the key symbol is not user-defined, i.e., is in the base references).

pub fn remove_dirty_symbol_references( &mut self, dirty_symbols: &HashSet<SymbolIdentifier>, )

Removes references for dirty (non-safe) symbols — O(dirty) instead of O(all).

This is the inverse of [retain_safe_symbol_references]: instead of iterating all entries and keeping safe ones, it directly removes entries for the given dirty set. Much faster when the dirty set is small relative to the total number of references.

Trait Implementations

impl Clone for SymbolReferences

fn clone(&self) -> SymbolReferences

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SymbolReferences

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SymbolReferences

fn default() -> SymbolReferences

Returns the “default value” for a type.

impl Eq for SymbolReferences

impl PartialEq for SymbolReferences

fn eq(&self, other: &SymbolReferences) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for SymbolReferences