brokk_bifrost_cpp/graph_support.rs
1//! The analyzer-resident products C++'s language logic resolves through.
2//!
3//! `CppAnalyzer` owns five moka caches, three `Arc<OnceLock<..>>` cells and one
4//! `PoolSafeMemo`; every one of them stays in `brokk-bifrost-analysis` because
5//! `IAnalyzer::update`/`update_all` rebuild the analyzer wholesale through
6//! `Self::from_inner`. What crosses the crate line is the *decision* that fills
7//! each cell -- the builders in [`crate::hierarchy`], [`crate::identity`] and
8//! [`crate::imports`] -- plus this trait, which is how a free function reaches
9//! back for a memoized product without naming the analyzer type.
10//!
11//! The census found no re-entrancy among these accessors, so this is a single
12//! tier rather than the two-tier split some fleet languages needed: the #1134
13//! reconciliation reads `visible_type_units`, which reads `include_target_index`
14//! and the supertrait's `import_statements`, and none of those reads back into
15//! reconciliation.
16//!
17//! Three members are load-bearing beyond their signature:
18//!
19//! * [`CppSource::visible_type_units`] is the moka-cached include-closure
20//! class table. Its *builder* is [`crate::hierarchy::build_cpp_visible_type_units`];
21//! the cell and its `test-support` build counter stay analyzer-side, so this
22//! accessor is the only way the reconciler reaches a warm table.
23//! * [`CppSource::raw_supertypes_of`] is
24//! `TreeSitterAnalyzer::raw_supertypes_of`, whose rows are crate-private to
25//! analysis; the analyzer hands the decoded base-specifier strings across.
26
27use crate::compile_context::CppCompileContext;
28use crate::graph::CppWorkspaceSource;
29use crate::imports::IncludeTargetIndex;
30use brokk_bifrost_core::analyzer::capabilities::{TypeAliasProvider, TypeHierarchyProvider};
31use brokk_bifrost_core::analyzer::model::{CppFieldLinkage, CppTemplateMetadata};
32use brokk_bifrost_core::analyzer::prepared_syntax::PreparedSyntaxTree;
33use brokk_bifrost_core::analyzer::{CodeUnit, CodeUnitIndex, ProjectFile};
34use std::sync::Arc;
35
36pub trait CppSource:
37 CodeUnitIndex + TypeAliasProvider + TypeHierarchyProvider + CppWorkspaceSource
38{
39 /// The workspace-wide `#include` resolution table, built once per analyzer
40 /// generation from [`IncludeTargetIndex::build`].
41 fn include_target_index(&self) -> &IncludeTargetIndex;
42
43 /// The declared base specifiers of `code_unit`, as written
44 /// (`TreeSitterAnalyzer::raw_supertypes_of`).
45 fn raw_supertypes_of(&self, code_unit: &CodeUnit) -> Vec<String>;
46
47 /// Every class-like or alias declaration reachable from `file` through its
48 /// `#include` closure, memoized per file. See this module's note.
49 fn visible_type_units(&self, file: &ProjectFile) -> Arc<Vec<CodeUnit>>;
50
51 /// The indexed source of `file` (`TreeSitterAnalyzer::file_source`).
52 fn file_source(&self, file: &ProjectFile) -> Option<String>;
53
54 /// The parsed tree and its source backing for `file`, from the analyzer's
55 /// query read cache.
56 ///
57 /// The single hottest member of this trait: the usage graph reaches it at
58 /// 27 call sites. The cache is *not* rebuilt per call -- `VisibilityIndex`
59 /// borrows the analyzer rather than cloning it precisely so this stays warm
60 /// across a scan (#1175), so an implementor must forward to the same
61 /// analyzer the query is running against.
62 fn prepared_syntax(&self, file: &ProjectFile) -> Option<Arc<PreparedSyntaxTree>>;
63
64 /// The persisted linkage fact for one C++ field, when the parser recorded
65 /// it. A missing fact requires the resolver's syntax fallback.
66 fn cpp_field_linkage(&self, code_unit: &CodeUnit) -> Option<CppFieldLinkage>;
67
68 /// The cached result of a preprocessor-visible include-reachability walk.
69 ///
70 /// The reference language affects only `__cplusplus` guards. Callers pass
71 /// that fact as a Boolean so cache keys do not retain the full reference
72 /// path.
73 fn cached_unconditional_include_reachability(
74 &self,
75 first: &ProjectFile,
76 donor_source: &ProjectFile,
77 reference_is_c: bool,
78 ) -> Option<bool>;
79
80 /// Store a completed preprocessor-visible include-reachability walk.
81 fn cache_unconditional_include_reachability(
82 &self,
83 first: &ProjectFile,
84 donor_source: &ProjectFile,
85 reference_is_c: bool,
86 reaches: bool,
87 );
88
89 /// The declaration's syntactic owner, which unlike
90 /// [`CodeUnitIndex::parent_of`] never falls back to a definition-row lookup.
91 fn structural_parent_of(&self, code_unit: &CodeUnit) -> Option<CodeUnit>;
92
93 /// The persisted C++ template metadata side table's row for `code_unit`.
94 fn template_metadata(&self, code_unit: &CodeUnit) -> Option<CppTemplateMetadata>;
95
96 /// The `compile_commands.json` entry governing `file`, if the workspace has
97 /// a compile database that names it. The only analyzer-resident product
98 /// [`crate::diagnostics`] needs.
99 fn compile_context_for(&self, file: &ProjectFile) -> Option<&CppCompileContext>;
100
101 /// Count a precise-parent resolution against the analyzer's counter.
102 ///
103 /// Called from production code in [`crate::graph::resolver`], which is why
104 /// it is on the trait at all; the counter itself stays on the analyzer.
105 ///
106 /// The default is a no-op because the two gates are not the same gate:
107 /// Cargo turns this crate's `test-support` on for the whole build graph
108 /// whenever `brokk-bifrost-analysis`'s dev-dependencies are in play, while
109 /// the analyzer-side counter field is `#[cfg(any(test, feature =
110 /// "test-support"))]` on *that* crate. The implementor overrides this
111 /// exactly when it has a counter to record into -- which is the build the
112 /// tests reading the counter run in.
113 #[cfg(any(test, feature = "test-support"))]
114 fn record_cpp_parent_resolution_for_test(&self) {}
115
116 /// Count a class-declaration-strength parse. See
117 /// [`Self::record_cpp_parent_resolution_for_test`].
118 #[cfg(any(test, feature = "test-support"))]
119 fn record_cpp_class_strength_parse_for_test(&self) {}
120}