Struct VisibilityIndex 

pub struct VisibilityIndex<'a> {
    pub visible_by_file: HashMap<ProjectFile, HashSet<CodeUnit>>,
    pub macro_include_protection_cells: Mutex<HashMap<ProjectFile, Arc<OnceLock<MacroIncludeProtection>>>>,
    pub macro_environment_cursors: Mutex<HashMap<(ProjectFile, ThreadId), MacroEnvironmentCursorCell>>,
    /* private fields */
}

Per-query C++ visibility facts.

The analyzer is borrowed, never cloned: TreeSitterAnalyzer::clone gives the clone a fresh, empty QueryReadCache on purpose (clones cross generations and overlays, where another generation’s hydrated states would be wrong). An index that owned a clone would therefore see an inactive read cache for every prepared_syntax call it makes, re-reading and re-parsing the same source from the store once per candidate instead of once per query — the #1175 blow-up, where one scan re-parsed a 4.8 MB generated header tens of thousands of times.

Fields

visible_by_file: HashMap<ProjectFile, HashSet<CodeUnit>>

macro_include_protection_cells: Mutex<HashMap<ProjectFile, Arc<OnceLock<MacroIncludeProtection>>>>

macro_environment_cursors: Mutex<HashMap<(ProjectFile, ThreadId), MacroEnvironmentCursorCell>>

Implementations

impl<'a> VisibilityIndex<'a>

pub fn cpp(&self) -> &'a dyn CppSource

pub fn build( cpp: &'a dyn CppSource, analyzer: &CppGraphSource<'_>, roots: &HashSet<ProjectFile>, ) -> Self

pub fn build_with_cancellation( cpp: &'a dyn CppSource, analyzer: &CppGraphSource<'_>, roots: &HashSet<ProjectFile>, cancellation: Option<&CancellationToken>, ) -> Self

pub fn is_visible(&self, file: &ProjectFile, target: &CodeUnit) -> bool

pub fn call_arity_evidence( &self, file: &ProjectFile, call: Node<'_>, source: &str, ) -> CallArityEvidence

pub fn function_macro_local_binding<'tree>( &self, file: &ProjectFile, statement: Node<'tree>, source: &str, ) -> Option<MacroLocalBinding<'tree>>

Recover a typed local declared by an active C function-like macro.

This is intentionally narrower than macro expansion. The replacement must parse as one declaration, and the invocation must bind every formal parameter to one structured argument. That is sufficient for declaration macros such as THIS(StorageAzure). An unavailable include can make the binding provisional without erasing its last known definition; an explicit conflicting definition still replaces it with Unsupported. Malformed and statement-producing macros also fail closed.

pub fn macro_event_cell(&self, file: &ProjectFile) -> MacroEventCell

pub fn macro_environment_cursor_cell( &self, file: &ProjectFile, ) -> MacroEnvironmentCursorCell

pub fn macro_environment( &self, file: &ProjectFile, before_byte: usize, ) -> Arc<MacroEnvironment>

pub fn names_a_macro_at( &self, file: &ProjectFile, name: &str, before_byte: usize, ) -> bool

Whether name is bound as a macro at before_byte in file, including a binding this environment cannot pin to one replacement (a conditional #define, or a function-like macro).

Self::object_macro_replacement_at collapses every such binding to None, which is indistinguishable from “not a macro at all”. A caller that must not read a macro token as an ordinary type name needs the two apart: an unexpandable macro is an unknown, a plain identifier is not.

pub fn macro_name_may_be_bound_at( &self, file: &ProjectFile, name: &str, before_byte: usize, ) -> bool

pub fn macro_binding_matches_target_at( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, name: &str, before_byte: usize, target: &CodeUnit, ) -> bool

Whether the active macro binding at this reference is the requested indexed definition. Name equality alone is not enough because two headers can define the same macro for different translation units.

pub fn resolve_ordinary_macro_reference( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, node: Node<'_>, source: &str, ) -> OrdinaryMacroReferenceResolution

Resolve an ordinary expression-position macro token at its exact byte.

Calls and preprocessor-condition tokens have separate resolution surfaces. Declaration names, macro parameters, and labels are not references. Keeping that role policy here makes forward and both inverse graph builders consume the same activation verdict (#2093).

pub fn recovered_c_reference_ranges( &self, file: &ProjectFile, root: Node<'_>, source: &str, limit: usize, ) -> RecoveredCReferenceRanges

Collect reference-capable C tokens beneath tree-sitter recovery nodes.

The ordinary census deliberately skips every ERROR subtree. This separate, precision-only frontier admits only roles that retain enough structure for the C usage graph to interpret independently (#2089). Macro evidence comes from this visibility index at the exact byte; no source-text parsing or terminal-name fallback is used.

pub fn macro_target_is_visible_candidate( &self, file: &ProjectFile, target: &CodeUnit, ) -> bool

Whether this target is an indexed macro visible from this file.

An unresolved conditional can make more than one same-name macro a possible active binding. Each possible target can keep the site as an unproven hit. A macro in an unrelated translation unit stays excluded.

pub fn object_macro_replacement_at( &self, file: &ProjectFile, name: &str, before_byte: usize, ) -> Option<String>

pub fn macro_include_protection( &self, file: &ProjectFile, ) -> MacroIncludeProtection

pub fn ordinary_type_import_cell( &self, file: &ProjectFile, ) -> OrdinaryTypeImportCell

pub fn project_using_index( &self, build: impl FnOnce() -> ProjectUsingIndex, ) -> &ProjectUsingIndex

pub fn all_visible_source_files(&self) -> Vec<ProjectFile>

pub fn source_is_visible( &self, root: &ProjectFile, source: &ProjectFile, ) -> bool

pub fn include_activation_for_source( &self, cpp: &dyn CppSource, file: &ProjectFile, prepared: &PreparedSyntaxTree, donor_source: &ProjectFile, ) -> Option<usize>

pub fn conditional_include_projections_for_source( &self, file: &ProjectFile, prepared: &PreparedSyntaxTree, donor_source: &ProjectFile, ) -> Arc<[ConditionalIncludeProjection]>

pub fn note_using_donor_activation_for_test(&self)

pub fn note_using_namespace_lookup_for_test(&self)

pub fn note_using_name_candidate_inspection_for_test(&self)

pub fn is_physically_visible( &self, file: &ProjectFile, target: &CodeUnit, ) -> bool

pub fn declaration_visible_at( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, declaration: &CodeUnit, reference_byte: usize, ) -> bool

Whether some declaration of declaration’s logical symbol is visible at reference_byte in file.

The question is asked of the logical symbol, not of the physical unit: an out-of-line body in a .cpp nobody includes is never itself visible, and it does not have to be - what makes the call legal is the header declaration that the reference file does include. Reading that relation through same_logical_callable rather than through signature strings is the same #2010 correction the gates make, and it matters here because the body and the declaration are exactly the pair that spells one parameter type two ways.

pub fn callable_arity_at_reference( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, candidate: &CodeUnit, reference_byte: usize, ) -> Option<CallableArity>

pub fn external_type_candidate_visible_at( &self, file: &ProjectFile, candidate: &CodeUnit, reference_byte: usize, ) -> bool

pub fn external_type_declaration_visible_at( &self, file: &ProjectFile, candidate: &CodeUnit, reference_byte: usize, ) -> bool

pub fn compile_proven_guards( &self, file: &ProjectFile, ) -> Arc<HashSet<PreprocessorGuard>>

The preprocessor facts the build proves for a reference sited in file (#2011).

Every -D that survives its command’s -D/-U ordering is a positive Defined fact, and a fact holds only when every compile configuration that governs the file agrees on it (intersection). The facts are strictly additive to the reference’s active guard set: they can prove a required guard, but the guard check itself is never weakened and no implication is ever inferred from source text.

A file with its own database entry answers from that entry alone (phase 1). A header takes its context from the translation units whose include closure reaches it, intersected across all of them (phase 2): the header is compiled once per including TU, so a fact holds for a header-sited reference only when every one of those compilations proves it. A reaching TU the database does not cover proves nothing, which empties the intersection. A file nothing covers or reaches has no facts and every check runs on source structure alone.

pub fn miss_requires_compile_context( &self, file: &ProjectFile, identifier: &str, reference: Node<'_>, ) -> bool

Whether a lookup miss for identifier in file is explainable by missing compile context (#2011): some same-name declaration is reachable through a conditional include whose required guards neither contradict the reference’s active guards nor follow from them, and the translation unit has no compile-commands entry that could decide the question. Callers surface this as an explicit “requires compile context” incompleteness instead of an indistinguishable miss.

A structurally disproven declaration (contradicting guards) and a TU whose compile context exists but does not prove the guard both answer false: those misses are decided, not incomplete.

pub fn external_type_candidate_visible_in_context( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, candidate: &CodeUnit, reference: Node<'_>, ) -> bool

pub fn is_exhaustive_same_fqn_type_declaration_family( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, candidate: &CodeUnit, ) -> bool

pub fn dependent_member_pointer_alias_visible_in_context( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, candidate: &CodeUnit, owner_components: &[String], reference: Node<'_>, ) -> bool

Prove a nested type alias used as a dependent member-pointer owner when its owning class has mutually-exclusive declarations. A common C++11 compatibility shape provides the owning class in one preprocessor branch and aliases it to a standard-library type in the other branch; the nested fallback alias is therefore not itself active in every branch even though the qualified owner API is.

This is deliberately narrower than ordinary type visibility. The caller has already recovered a member-pointer owner path from the CST; this helper additionally requires the target’s structured parent to match that path, physical source visibility, and exact preprocessor guard agreement with the parent declaration. Only then may the parent’s direct/complementary same-FQN visibility stand in for the nested terminal’s active-branch check.

pub fn external_type_candidate_guard_compatible_in_context( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, candidate: &CodeUnit, reference: Node<'_>, ) -> bool

Check a type candidate’s preprocessor/import context without imposing ordinary declaration-before-reference ordering for same-file peers.

C++ class scope makes member names visible throughout the complete class, including a trailing return type that appears before the member alias declaration in source order. Callers must first prove that the reference is inside the candidate’s indexed class owner; this helper only relaxes the byte-order predicate while retaining guard and include activation checks.

pub fn type_candidate_may_be_visible_before_reference( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, candidate: &CodeUnit, reference_byte: usize, ) -> bool

pub fn preprocessor_guards_stable_between( &self, file: &ProjectFile, start_byte: usize, end_byte: usize, guards: &HashSet<PreprocessorGuard>, ) -> bool

pub fn resolve_type( &self, file: &ProjectFile, raw_name: &str, ) -> Option<CodeUnit>

pub fn unique_visible_parameter_type_fallback( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, node: Node<'_>, source: &str, ) -> Option<CodeUnit>

Mirror forward navigation’s visible-name fallback for a bare parameter type after lexical owner and inheritance lookup is exhausted.

Generated or otherwise unindexed base classes can hide the alias that makes a parameter type valid C++. Accept the fallback only when every include-visible class or alias with that spelling canonicalizes to one logical type. A shadowing local type resolves lexically before this path, while distinct visible types keep the result ambiguous.

pub fn resolve_type_node_result( &self, file: &ProjectFile, node: Node<'_>, source: &str, ) -> Result<Option<CodeUnit>, CppTemplateResolutionError>

pub fn resolve_type_node_primary( &self, file: &ProjectFile, node: Node<'_>, source: &str, ) -> Option<CodeUnit>

pub fn resolve_template_arguments( &self, file: &ProjectFile, primary: CodeUnit, arguments: &[CppTemplateExpression], ) -> Result<CodeUnit, CppTemplateResolutionError>

pub fn resolve_type_components_lexically( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, components: &[String], global: bool, lexical_scope: &[String], ) -> LexicalTypeResolution

pub fn resolve_type_components_lexically_for_forward( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, components: &[String], global: bool, lexical_scope: &[String], ) -> LexicalTypeResolution

pub fn resolve_type_components_lexically_for_target( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, components: &[String], global: bool, lexical_scope: &[String], target: &CodeUnit, ) -> LexicalTypeResolution

pub fn coarse_unqualified_type_reference_may_resolve( &self, file: &ProjectFile, name: &str, ) -> bool

pub fn structured_type_reference_may_resolve_to_target( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, components: &[String], global: bool, lexical_scope: &[String], target: &CodeUnit, ) -> bool

pub fn target_preserving_reference_namespace( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, identifier: &str, target: &CodeUnit, ) -> Option<Vec<String>>

pub fn resolve_imported_type_candidate( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, target: &CodeUnit, target_components: &[String], direct_target: Option<&CodeUnit>, preserve_alias: bool, ) -> LexicalTypeResolution

pub fn inherited_injected_class_owner( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, enclosing_owner: &CodeUnit, injected_name: &str, ) -> Option<CodeUnit>

Resolve a base class through its injected class name at the nearest inheritance tier. Distinct same-named bases at that tier are ambiguous.

pub fn resolve_callable_value_components_lexically( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, owner_components: &[String], member_name: &str, global: bool, lexical_scope: &[String], ) -> LexicalCallableValueResolution

pub fn canonical_type_unit( &self, analyzer: &CppGraphSource<'_>, visible_from: &ProjectFile, unit: &CodeUnit, ) -> Option<CodeUnit>

pub fn canonical_visible_full_type_unit( &self, analyzer: &CppGraphSource<'_>, visible_from: &ProjectFile, unit: &CodeUnit, ) -> Option<CodeUnit>

pub fn structured_alias_primary_preserves_target( &self, analyzer: &CppGraphSource<'_>, visible_from: &ProjectFile, candidate: &CodeUnit, target: &CodeUnit, ) -> bool

pub fn structured_class_alias_resolves_to_target( &self, analyzer: &CppGraphSource<'_>, visible_from: &ProjectFile, alias: &CodeUnit, target: &CodeUnit, ) -> bool

pub fn structured_class_alias_path_preserves_target( &self, analyzer: &CppGraphSource<'_>, visible_from: &ProjectFile, alias: &CodeUnit, target: &CodeUnit, ) -> bool

Return true when a class-owned alias names the requested type as one structured qualifier in its target path.

A dependent target such as Primary<T>::Type cannot resolve to one indexed class. Forward lookup can still retain Primary as its bounded canonical identity. Inverse lookup needs the same evidence when later references use only the alias spelling.

pub fn template_alias_arguments_preserve_target( &self, analyzer: &CppGraphSource<'_>, visible_from: &ProjectFile, alias: &CodeUnit, arguments: &[CppTemplateExpression], target: &CodeUnit, ) -> bool

pub fn is_primary_template(&self, unit: &CodeUnit) -> bool

pub fn is_template_specialization(&self, unit: &CodeUnit) -> bool

pub fn same_template_owner_identity( &self, left: &CodeUnit, right: &CodeUnit, ) -> bool

pub fn same_template_member_identity( &self, analyzer: &CppGraphSource<'_>, left: &CodeUnit, right: &CodeUnit, ) -> bool

pub fn unique_type_candidate_preserving_target( &self, analyzer: &CppGraphSource<'_>, visible_from: &ProjectFile, candidates: &[&CodeUnit], target: &CodeUnit, ) -> Option<CodeUnit>

pub fn same_fqn_type_spelling_for_target<'b>( &self, analyzer: &CppGraphSource<'_>, visible_from: &ProjectFile, candidates: &[&'b CodeUnit], target: &CodeUnit, ) -> Option<&'b CodeUnit>

The declaration a same-file same-FQN family stands for when a reference names target, or None when the candidates are not one family or the family does not name target.

A translation unit cannot hold two different types under one qualified name, so several same-kind declarations of one FQN in one file are alternate spellings of one entity - the configuration branches of an #if family, for example log4cxx’s logchar, which aliases char in the UTF-8 branch and UniChar in the unichar branch. Their alias targets differ; canonicalizing each branch on its own and then demanding agreement reports an ambiguity that denies every declaration in the family its usages (#1845). The family names target when it declares it, or when one branch’s alias chain reaches it.

Declarations in different files or namespaces are distinct entities and are deliberately excluded: their disagreement is a real ambiguity.

pub fn alternate_same_fqn_type_declarations( &self, analyzer: &CppGraphSource<'_>, candidates: &[&CodeUnit], target: &CodeUnit, ) -> bool

pub fn complementary_same_fqn_type_declarations( &self, analyzer: &CppGraphSource<'_>, candidates: &[&CodeUnit], target: &CodeUnit, ) -> bool

pub fn resolves_to_type( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, raw_name: &str, target: &CodeUnit, ) -> bool

pub fn alias_target(&self, alias: &CodeUnit) -> Option<CodeUnit>

pub fn same_logical_callable( &self, analyzer: &CppGraphSource<'_>, left: &CodeUnit, right: &CodeUnit, ) -> bool

Whether two callable declarations declare one function.

same_logical_symbol compares the persisted signature strings, which embed each parameter type exactly as it was spelled. A header declaration written inside namespace zmq { class dist_t { ... } } says send_to_matching(msg_t *) while its out-of-line body at file scope says zmq::msg_t *, so the string comparison reports two symbols where C++ ([basic.def], [dcl.fct]) sees one declaration and one definition. This resolves the written parameter names before comparing them and reports the same answer the language does for the cases it can prove.

Everything it cannot prove stays two symbols: a template declaration, a parameter with no comparable shape, a name that resolves on one side only, and an alias chain it cannot follow safely (#2010).

pub fn canonical_type_for_reference( &self, file: &ProjectFile, raw_name: &str, ) -> Option<CodeUnit>

pub fn parser_alias_resolves_to_type( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, raw_name: &str, target: &CodeUnit, ) -> bool

pub fn resolve_named( &self, file: &ProjectFile, raw_name: &str, kind: TargetKind, ) -> Option<CodeUnit>

pub fn contains_named_symbol( &self, file: &ProjectFile, raw_name: &str, kind: TargetKind, target: &CodeUnit, ) -> bool

pub fn named_candidates( &self, file: &ProjectFile, raw_name: &str, kind: TargetKind, ) -> Vec<CodeUnit>

pub fn resolve_known_non_target( &self, file: &ProjectFile, raw_name: &str, kind: TargetKind, target: &CodeUnit, ) -> bool

pub fn resolve_call_return_binding( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, raw_name: &str, arity: usize, lexical_namespace: Option<&str>, direct_type: Option<&CodeUnit>, ) -> Option<CppScanBinding>

pub fn resolve_call_return_binding_without_arity( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, raw_name: &str, lexical_namespace: Option<&str>, direct_type: Option<&CodeUnit>, ) -> (bool, Option<CppScanBinding>)

pub fn visible_identifier_candidates<'b>( &'b self, file: &ProjectFile, identifier: &str, ) -> impl Iterator<Item = &'b CodeUnit> + 'b

pub fn visible_type_reference_component_names_for_target( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, target: &CodeUnit, ) -> HashSet<String>

Return terminal reference names that can denote target from file.

The indexed candidate table covers ordinary declarations and aliases; parser-only aliases are read through their per-file cells so this path never reparses a source that has already been inspected by the visibility index.

pub fn indexed_structural_class_scope( &self, file: &ProjectFile, class: Node<'_>, source: &str, ) -> Option<Vec<String>>

pub fn indexed_enclosing_owner_scope( &self, analyzer: &CppGraphSource<'_>, file: &ProjectFile, node: Node<'_>, ) -> Option<Vec<String>>

pub fn callable_is_constructor_declaration( &self, analyzer: &CppGraphSource<'_>, candidate: &CodeUnit, ) -> bool

pub fn callable_is_deduction_guide_declaration( &self, analyzer: &CppGraphSource<'_>, candidate: &CodeUnit, ) -> bool

Whether a callable declaration is a class-template deduction guide.

Tree-sitter represents Box(T) -> Box<T>; as a declaration with no type field whose function declarator owns a trailing return type. This structured shape distinguishes a guide from both a constructor (no trailing return) and an ordinary trailing-return function (an auto type field).

pub fn callable_is_template_declaration( &self, analyzer: &CppGraphSource<'_>, candidate: &CodeUnit, ) -> bool

Whether a callable occurrence is directly wrapped by a C++ template declaration. This deliberately inspects declaration syntax instead of inferring template status from the rendered signature.

pub fn type_name_candidates<'b>( &'b self, file: &ProjectFile, normalized: &str, ) -> Vec<&'b CodeUnit>

pub fn visible_members_for_owner_name<'b>( &'b self, file: &ProjectFile, owner: &CodeUnit, name: &str, ) -> Vec<&'b CodeUnit>

pub fn visible_member_for_owner_name( &self, file: &ProjectFile, owner: &CodeUnit, name: &str, ) -> VisibleMemberResolution

pub fn type_candidates<'b>( &'b self, file: &ProjectFile, normalized: &str, ) -> Vec<&'b CodeUnit>

pub fn named_candidates_for_normalized<'b>( &'b self, file: &ProjectFile, normalized: &str, kind: TargetKind, ) -> Vec<&'b CodeUnit>

pub fn candidate_units<'b>( &'b self, file: &ProjectFile, normalized: &str, kind: TargetKind, ) -> Vec<&'b CodeUnit>