foundry_evm_coverage/
lib.rs

Help
1//! # foundry-evm-coverage
2//!
3//! EVM bytecode coverage analysis.
4
5#![cfg_attr(not(test), warn(unused_crate_dependencies))]
6#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
7
8#[macro_use]
9extern crate tracing;
10
11use alloy_primitives::{
12    map::{B256HashMap, HashMap},
13    Bytes,
14};
15use analysis::SourceAnalysis;
16use eyre::Result;
17use foundry_compilers::artifacts::sourcemap::SourceMap;
18use semver::Version;
19use std::{
20    collections::BTreeMap,
21    fmt::Display,
22    num::NonZeroU32,
23    ops::{Deref, DerefMut, Range},
24    path::{Path, PathBuf},
25    sync::Arc,
26};
27
28pub mod analysis;
29pub mod anchors;
30
31mod inspector;
32pub use inspector::CoverageCollector;
33
34/// A coverage report.
35///
36/// A coverage report contains coverage items and opcodes corresponding to those items (called
37/// "anchors"). A single coverage item may be referred to by multiple anchors.
38#[derive(Clone, Debug, Default)]
39pub struct CoverageReport {
40    /// A map of source IDs to the source path.
41    pub source_paths: HashMap<(Version, usize), PathBuf>,
42    /// A map of source paths to source IDs.
43    pub source_paths_to_ids: HashMap<(Version, PathBuf), usize>,
44    /// All coverage items for the codebase, keyed by the compiler version.
45    pub analyses: HashMap<Version, SourceAnalysis>,
46    /// All item anchors for the codebase, keyed by their contract ID.
47    pub anchors: HashMap<ContractId, (Vec<ItemAnchor>, Vec<ItemAnchor>)>,
48    /// All the bytecode hits for the codebase.
49    pub bytecode_hits: HashMap<ContractId, HitMap>,
50    /// The bytecode -> source mappings.
51    pub source_maps: HashMap<ContractId, (SourceMap, SourceMap)>,
52}
53
54impl CoverageReport {
55    /// Add a source file path.
56    pub fn add_source(&mut self, version: Version, source_id: usize, path: PathBuf) {
57        self.source_paths.insert((version.clone(), source_id), path.clone());
58        self.source_paths_to_ids.insert((version, path), source_id);
59    }
60
61    /// Get the source ID for a specific source file path.
62    pub fn get_source_id(&self, version: Version, path: PathBuf) -> Option<usize> {
63        self.source_paths_to_ids.get(&(version, path)).copied()
64    }
65
66    /// Add the source maps.
67    pub fn add_source_maps(
68        &mut self,
69        source_maps: impl IntoIterator<Item = (ContractId, (SourceMap, SourceMap))>,
70    ) {
71        self.source_maps.extend(source_maps);
72    }
73
74    /// Add a [`SourceAnalysis`] to this report.
75    pub fn add_analysis(&mut self, version: Version, analysis: SourceAnalysis) {
76        self.analyses.insert(version, analysis);
77    }
78
79    /// Add anchors to this report.
80    pub fn add_anchors(
81        &mut self,
82        anchors: impl IntoIterator<Item = (ContractId, (Vec<ItemAnchor>, Vec<ItemAnchor>))>,
83    ) {
84        self.anchors.extend(anchors);
85    }
86
87    /// Returns an iterator over coverage summaries by source file path.
88    pub fn summary_by_file(&self) -> impl Iterator<Item = (&Path, CoverageSummary)> {
89        self.by_file(|summary: &mut CoverageSummary, item| summary.add_item(item))
90    }
91
92    /// Returns an iterator over coverage items by source file path.
93    pub fn items_by_file(&self) -> impl Iterator<Item = (&Path, Vec<&CoverageItem>)> {
94        self.by_file(|list: &mut Vec<_>, item| list.push(item))
95    }
96
97    fn by_file<'a, T: Default>(
98        &'a self,
99        mut f: impl FnMut(&mut T, &'a CoverageItem),
100    ) -> impl Iterator<Item = (&'a Path, T)> {
101        let mut by_file: BTreeMap<&Path, T> = BTreeMap::new();
102        for (version, items) in &self.analyses {
103            for item in items.all_items() {
104                let key = (version.clone(), item.loc.source_id);
105                let Some(path) = self.source_paths.get(&key) else { continue };
106                f(by_file.entry(path).or_default(), item);
107            }
108        }
109        by_file.into_iter()
110    }
111
112    /// Processes data from a [`HitMap`] and sets hit counts for coverage items in this coverage
113    /// map.
114    ///
115    /// This function should only be called *after* all the relevant sources have been processed and
116    /// added to the map (see [`add_source`](Self::add_source)).
117    pub fn add_hit_map(
118        &mut self,
119        contract_id: &ContractId,
120        hit_map: &HitMap,
121        is_deployed_code: bool,
122    ) -> Result<()> {
123        // Add bytecode level hits.
124        self.bytecode_hits
125            .entry(contract_id.clone())
126            .and_modify(|m| m.merge(hit_map))
127            .or_insert_with(|| hit_map.clone());
128
129        // Add source level hits.
130        if let Some(anchors) = self.anchors.get(contract_id) {
131            let anchors = if is_deployed_code { &anchors.1 } else { &anchors.0 };
132            for anchor in anchors {
133                if let Some(hits) = hit_map.get(anchor.instruction) {
134                    self.analyses
135                        .get_mut(&contract_id.version)
136                        .and_then(|items| items.all_items_mut().get_mut(anchor.item_id as usize))
137                        .expect("Anchor refers to non-existent coverage item")
138                        .hits += hits.get();
139                }
140            }
141        }
142
143        Ok(())
144    }
145
146    /// Retains all the coverage items specified by `predicate`.
147    ///
148    /// This function should only be called after all the sources were used, otherwise, the output
149    /// will be missing the ones that are dependent on them.
150    pub fn retain_sources(&mut self, mut predicate: impl FnMut(&Path) -> bool) {
151        self.analyses.retain(|version, analysis| {
152            analysis.all_items_mut().retain(|item| {
153                self.source_paths
154                    .get(&(version.clone(), item.loc.source_id))
155                    .map(|path| predicate(path))
156                    .unwrap_or(false)
157            });
158            !analysis.all_items().is_empty()
159        });
160    }
161}
162
163/// A collection of [`HitMap`]s.
164#[derive(Clone, Debug, Default)]
165pub struct HitMaps(pub B256HashMap<HitMap>);
166
167impl HitMaps {
168    /// Merges two `Option<HitMaps>`.
169    pub fn merge_opt(a: &mut Option<Self>, b: Option<Self>) {
170        match (a, b) {
171            (_, None) => {}
172            (a @ None, Some(b)) => *a = Some(b),
173            (Some(a), Some(b)) => a.merge(b),
174        }
175    }
176
177    /// Merges two `HitMaps`.
178    pub fn merge(&mut self, other: Self) {
179        self.reserve(other.len());
180        for (code_hash, other) in other.0 {
181            self.entry(code_hash).and_modify(|e| e.merge(&other)).or_insert(other);
182        }
183    }
184
185    /// Merges two `HitMaps`.
186    pub fn merged(mut self, other: Self) -> Self {
187        self.merge(other);
188        self
189    }
190}
191
192impl Deref for HitMaps {
193    type Target = B256HashMap<HitMap>;
194
195    fn deref(&self) -> &Self::Target {
196        &self.0
197    }
198}
199
200impl DerefMut for HitMaps {
201    fn deref_mut(&mut self) -> &mut Self::Target {
202        &mut self.0
203    }
204}
205
206/// Hit data for an address.
207///
208/// Contains low-level data about hit counters for the instructions in the bytecode of a contract.
209#[derive(Clone, Debug)]
210pub struct HitMap {
211    bytecode: Bytes,
212    hits: HashMap<u32, u32>,
213}
214
215impl HitMap {
216    /// Create a new hitmap with the given bytecode.
217    #[inline]
218    pub fn new(bytecode: Bytes) -> Self {
219        Self { bytecode, hits: HashMap::with_capacity_and_hasher(1024, Default::default()) }
220    }
221
222    /// Returns the bytecode.
223    #[inline]
224    pub fn bytecode(&self) -> &Bytes {
225        &self.bytecode
226    }
227
228    /// Returns the number of hits for the given program counter.
229    #[inline]
230    pub fn get(&self, pc: u32) -> Option<NonZeroU32> {
231        NonZeroU32::new(self.hits.get(&pc).copied().unwrap_or(0))
232    }
233
234    /// Increase the hit counter by 1 for the given program counter.
235    #[inline]
236    pub fn hit(&mut self, pc: u32) {
237        self.hits(pc, 1)
238    }
239
240    /// Increase the hit counter by `hits` for the given program counter.
241    #[inline]
242    pub fn hits(&mut self, pc: u32, hits: u32) {
243        *self.hits.entry(pc).or_default() += hits;
244    }
245
246    /// Merge another hitmap into this, assuming the bytecode is consistent
247    pub fn merge(&mut self, other: &Self) {
248        self.hits.reserve(other.len());
249        for (pc, hits) in other.iter() {
250            self.hits(pc, hits);
251        }
252    }
253
254    /// Returns an iterator over all the program counters and their hit counts.
255    #[inline]
256    pub fn iter(&self) -> impl Iterator<Item = (u32, u32)> + '_ {
257        self.hits.iter().map(|(&pc, &hits)| (pc, hits))
258    }
259
260    /// Returns the number of program counters hit in the hitmap.
261    #[inline]
262    pub fn len(&self) -> usize {
263        self.hits.len()
264    }
265
266    /// Returns `true` if the hitmap is empty.
267    #[inline]
268    pub fn is_empty(&self) -> bool {
269        self.hits.is_empty()
270    }
271}
272
273/// A unique identifier for a contract
274#[derive(Clone, Debug, PartialEq, Eq, Hash)]
275pub struct ContractId {
276    pub version: Version,
277    pub source_id: usize,
278    pub contract_name: Arc<str>,
279}
280
281impl Display for ContractId {
282    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
283        write!(
284            f,
285            "Contract \"{}\" (solc {}, source ID {})",
286            self.contract_name, self.version, self.source_id
287        )
288    }
289}
290
291/// An item anchor describes what instruction marks a [CoverageItem] as covered.
292#[derive(Clone, Debug)]
293pub struct ItemAnchor {
294    /// The program counter for the opcode of this anchor.
295    pub instruction: u32,
296    /// The item ID this anchor points to.
297    pub item_id: u32,
298}
299
300impl Display for ItemAnchor {
301    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
302        write!(f, "IC {} -> Item {}", self.instruction, self.item_id)
303    }
304}
305
306#[derive(Clone, Debug)]
307pub enum CoverageItemKind {
308    /// An executable line in the code.
309    Line,
310    /// A statement in the code.
311    Statement,
312    /// A branch in the code.
313    Branch {
314        /// The ID that identifies the branch.
315        ///
316        /// There may be multiple items with the same branch ID - they belong to the same branch,
317        /// but represent different paths.
318        branch_id: u32,
319        /// The path ID for this branch.
320        ///
321        /// The first path has ID 0, the next ID 1, and so on.
322        path_id: u32,
323        /// If true, then the branch anchor is the first opcode within the branch source range.
324        is_first_opcode: bool,
325    },
326    /// A function in the code.
327    Function {
328        /// The name of the function.
329        name: String,
330    },
331}
332
333#[derive(Clone, Debug)]
334pub struct CoverageItem {
335    /// The coverage item kind.
336    pub kind: CoverageItemKind,
337    /// The location of the item in the source code.
338    pub loc: SourceLocation,
339    /// The number of times this item was hit.
340    pub hits: u32,
341}
342
343impl Display for CoverageItem {
344    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
345        match &self.kind {
346            CoverageItemKind::Line => {
347                write!(f, "Line")?;
348            }
349            CoverageItemKind::Statement => {
350                write!(f, "Statement")?;
351            }
352            CoverageItemKind::Branch { branch_id, path_id, .. } => {
353                write!(f, "Branch (branch: {branch_id}, path: {path_id})")?;
354            }
355            CoverageItemKind::Function { name } => {
356                write!(f, r#"Function "{name}""#)?;
357            }
358        }
359        write!(f, " (location: {}, hits: {})", self.loc, self.hits)
360    }
361}
362
363/// A source location.
364#[derive(Clone, Debug)]
365pub struct SourceLocation {
366    /// The source ID.
367    pub source_id: usize,
368    /// The contract this source range is in.
369    pub contract_name: Arc<str>,
370    /// Byte range.
371    pub bytes: Range<u32>,
372    /// Line range. Indices are 1-based.
373    pub lines: Range<u32>,
374}
375
376impl Display for SourceLocation {
377    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
378        write!(f, "source ID {}, lines {:?}, bytes {:?}", self.source_id, self.lines, self.bytes)
379    }
380}
381
382impl SourceLocation {
383    /// Returns the length of the byte range.
384    pub fn len(&self) -> u32 {
385        self.bytes.len() as u32
386    }
387
388    /// Returns true if the byte range is empty.
389    pub fn is_empty(&self) -> bool {
390        self.len() == 0
391    }
392}
393
394/// Coverage summary for a source file.
395#[derive(Clone, Debug, Default)]
396pub struct CoverageSummary {
397    /// The number of executable lines in the source file.
398    pub line_count: usize,
399    /// The number of lines that were hit.
400    pub line_hits: usize,
401    /// The number of statements in the source file.
402    pub statement_count: usize,
403    /// The number of statements that were hit.
404    pub statement_hits: usize,
405    /// The number of branches in the source file.
406    pub branch_count: usize,
407    /// The number of branches that were hit.
408    pub branch_hits: usize,
409    /// The number of functions in the source file.
410    pub function_count: usize,
411    /// The number of functions hit.
412    pub function_hits: usize,
413}
414
415impl CoverageSummary {
416    /// Creates a new, empty coverage summary.
417    pub fn new() -> Self {
418        Self::default()
419    }
420
421    /// Creates a coverage summary from a collection of coverage items.
422    pub fn from_items<'a>(items: impl IntoIterator<Item = &'a CoverageItem>) -> Self {
423        let mut summary = Self::default();
424        summary.add_items(items);
425        summary
426    }
427
428    /// Adds another coverage summary to this one.
429    pub fn merge(&mut self, other: &Self) {
430        let Self {
431            line_count,
432            line_hits,
433            statement_count,
434            statement_hits,
435            branch_count,
436            branch_hits,
437            function_count,
438            function_hits,
439        } = self;
440        *line_count += other.line_count;
441        *line_hits += other.line_hits;
442        *statement_count += other.statement_count;
443        *statement_hits += other.statement_hits;
444        *branch_count += other.branch_count;
445        *branch_hits += other.branch_hits;
446        *function_count += other.function_count;
447        *function_hits += other.function_hits;
448    }
449
450    /// Adds a coverage item to this summary.
451    pub fn add_item(&mut self, item: &CoverageItem) {
452        match item.kind {
453            CoverageItemKind::Line => {
454                self.line_count += 1;
455                if item.hits > 0 {
456                    self.line_hits += 1;
457                }
458            }
459            CoverageItemKind::Statement => {
460                self.statement_count += 1;
461                if item.hits > 0 {
462                    self.statement_hits += 1;
463                }
464            }
465            CoverageItemKind::Branch { .. } => {
466                self.branch_count += 1;
467                if item.hits > 0 {
468                    self.branch_hits += 1;
469                }
470            }
471            CoverageItemKind::Function { .. } => {
472                self.function_count += 1;
473                if item.hits > 0 {
474                    self.function_hits += 1;
475                }
476            }
477        }
478    }
479
480    /// Adds multiple coverage items to this summary.
481    pub fn add_items<'a>(&mut self, items: impl IntoIterator<Item = &'a CoverageItem>) {
482        for item in items {
483            self.add_item(item);
484        }
485    }
486}
foundry_evm_coverage/lib.rs

foundry_evm_coverage/
lib.rs
