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::graph::resolver::SourceUsingIndex;
30use crate::imports::IncludeTargetIndex;
31use brokk_bifrost_core::analyzer::capabilities::{TypeAliasProvider, TypeHierarchyProvider};
32use brokk_bifrost_core::analyzer::model::{CppFieldLinkage, CppTemplateMetadata};
33use brokk_bifrost_core::analyzer::prepared_syntax::PreparedSyntaxTree;
34use brokk_bifrost_core::analyzer::{CodeUnit, CodeUnitIndex, ProjectFile};
35use std::sync::Arc;
36
37pub trait CppSource:
38 CodeUnitIndex + TypeAliasProvider + TypeHierarchyProvider + CppWorkspaceSource
39{
40 /// The workspace-wide `#include` resolution table, built once per analyzer
41 /// generation from [`IncludeTargetIndex::build`].
42 fn include_target_index(&self) -> &IncludeTargetIndex;
43
44 /// The declared base specifiers of `code_unit`, as written
45 /// (`TreeSitterAnalyzer::raw_supertypes_of`).
46 fn raw_supertypes_of(&self, code_unit: &CodeUnit) -> Vec<String>;
47
48 /// Every class-like or alias declaration reachable from `file` through its
49 /// `#include` closure, memoized per file. See this module's note.
50 fn visible_type_units(&self, file: &ProjectFile) -> Arc<Vec<CodeUnit>>;
51
52 /// [`Self::visible_type_units`] under a caller's deadline.
53 ///
54 /// `None` means the include-closure walk stopped short. Nothing is
55 /// memoized in that case: a truncated class table is indistinguishable
56 /// from a file that simply sees fewer types, so every later base-specifier
57 /// resolution reading it would silently lose ancestors.
58 ///
59 /// This is the shape issue #1748 needed. The closure walk is individually
60 /// cheap -- a fraction of a millisecond to about 180 ms -- but the
61 /// descendant-index build above it runs one per class in the workspace,
62 /// which on a large tree is tens of thousands of them inside a single
63 /// request that asked for thirty seconds.
64 fn visible_type_units_while(
65 &self,
66 file: &ProjectFile,
67 keep_going: &dyn Fn() -> bool,
68 ) -> Option<Arc<Vec<CodeUnit>>>;
69
70 /// The per-file structured using index (ordinary using declarations and
71 /// using-directives with their guard environments), memoized per file.
72 /// Built by [`crate::graph::extractor::build_source_using_index`], which is
73 /// a pure function of the file's parsed content.
74 ///
75 /// Memoized on the analyzer rather than on `VisibilityIndex` because a
76 /// fresh visibility index is built per usage query: rebuilding the index
77 /// per query re-walked a 9.5 MB amalgamation's AST once per candidate
78 /// (issue #1927).
79 fn source_using_index(&self, file: &ProjectFile) -> Arc<SourceUsingIndex>;
80
81 /// The indexed source of `file` (`TreeSitterAnalyzer::file_source`).
82 fn file_source(&self, file: &ProjectFile) -> Option<String>;
83
84 /// The parsed tree and its source backing for `file`, from the analyzer's
85 /// query read cache.
86 ///
87 /// The single hottest member of this trait: the usage graph reaches it at
88 /// 27 call sites. The cache is *not* rebuilt per call -- `VisibilityIndex`
89 /// borrows the analyzer rather than cloning it precisely so this stays warm
90 /// across a scan (#1175), so an implementor must forward to the same
91 /// analyzer the query is running against.
92 fn prepared_syntax(&self, file: &ProjectFile) -> Option<Arc<PreparedSyntaxTree>>;
93
94 /// The persisted linkage fact for one C++ field, when the parser recorded
95 /// it. A missing fact requires the resolver's syntax fallback.
96 fn cpp_field_linkage(&self, code_unit: &CodeUnit) -> Option<CppFieldLinkage>;
97
98 /// The cached result of a preprocessor-visible include-reachability walk.
99 ///
100 /// The reference language affects only `__cplusplus` guards. Callers pass
101 /// that fact as a Boolean so cache keys do not retain the full reference
102 /// path.
103 fn cached_unconditional_include_reachability(
104 &self,
105 first: &ProjectFile,
106 donor_source: &ProjectFile,
107 reference_is_c: bool,
108 ) -> Option<bool>;
109
110 /// Store a completed preprocessor-visible include-reachability walk.
111 fn cache_unconditional_include_reachability(
112 &self,
113 first: &ProjectFile,
114 donor_source: &ProjectFile,
115 reference_is_c: bool,
116 reaches: bool,
117 );
118
119 /// The declaration's syntactic owner, which unlike
120 /// [`CodeUnitIndex::parent_of`] never falls back to a definition-row lookup.
121 fn structural_parent_of(&self, code_unit: &CodeUnit) -> Option<CodeUnit>;
122
123 /// The persisted C++ template metadata side table's row for `code_unit`.
124 fn template_metadata(&self, code_unit: &CodeUnit) -> Option<CppTemplateMetadata>;
125
126 /// Every distinct `compile_commands.json` configuration governing `file`,
127 /// empty when the workspace has no compile database entry naming it. The
128 /// only analyzer-resident product [`crate::diagnostics`] needs.
129 ///
130 /// A file the build compiles in several configurations yields several
131 /// contexts, because their include closures can disagree about a name.
132 fn compile_contexts_for(&self, file: &ProjectFile) -> &[CppCompileContext];
133
134 /// Count a precise-parent resolution against the analyzer's counter.
135 ///
136 /// Called from production code in [`crate::graph::resolver`], which is why
137 /// it is on the trait at all; the counter itself stays on the analyzer.
138 ///
139 /// The default is a no-op because the two gates are not the same gate:
140 /// Cargo turns this crate's `test-support` on for the whole build graph
141 /// whenever `brokk-bifrost-analysis`'s dev-dependencies are in play, while
142 /// the analyzer-side counter field is `#[cfg(any(test, feature =
143 /// "test-support"))]` on *that* crate. The implementor overrides this
144 /// exactly when it has a counter to record into -- which is the build the
145 /// tests reading the counter run in.
146 #[cfg(any(test, feature = "test-support"))]
147 fn record_cpp_parent_resolution_for_test(&self) {}
148
149 /// Count a class-declaration-strength parse. See
150 /// [`Self::record_cpp_parent_resolution_for_test`].
151 #[cfg(any(test, feature = "test-support"))]
152 fn record_cpp_class_strength_parse_for_test(&self) {}
153
154 /// Count a guard-ancestry inspection during a per-file using-index build.
155 /// See [`Self::record_cpp_parent_resolution_for_test`].
156 #[cfg(any(test, feature = "test-support"))]
157 fn record_using_guard_context_inspection_for_test(&self) {}
158}