From 5da81a1ff05fc3433590f062b253406e4ffecd82 Mon Sep 17 00:00:00 2001 From: ksew1 Date: Fri, 13 Feb 2026 13:38:17 +0100 Subject: [PATCH 1/3] Add starkup installation to README commit-id:6f45aa1a --- README.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 956866a..0144043 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,23 @@ ## Installation -You can install `cairo-coverage` using [asdf](https://asdf-vm.com/guide/getting-started.html) +You can install `cairo-coverage` using [starkup](https://starkup.sh/), [asdf](https://asdf-vm.com/guide/getting-started.html) or the installation script. -### asdf (recommended): +### starkup (recommended): + +Starkup helps you install all the tools used to develop packages in Cairo and write contracts for Starknet. + +> ℹ️ Info +> +> When using starkup on Windows, please use WSL, as it only works on macOS and Linux. + +Run the following in your terminal, then follow the onscreen instructions: +```shell +curl --proto '=https' --tlsv1.2 -sSf https://sh.starkup.sh | sh +``` + +### asdf: ```shell asdf plugin add cairo-coverage From fbe879c060374e806309f5ffc800fe8900a3ac53 Mon Sep 17 00:00:00 2001 From: ksew1 Date: Fri, 13 Feb 2026 13:39:33 +0100 Subject: [PATCH 2/3] Add todo marker for libfuncs filter implementation commit-id:bccff004 --- crates/cairo-coverage-core/src/build/filter/libfuncs.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/crates/cairo-coverage-core/src/build/filter/libfuncs.rs b/crates/cairo-coverage-core/src/build/filter/libfuncs.rs index 7313ebf..00dacea 100644 --- a/crates/cairo-coverage-core/src/build/filter/libfuncs.rs +++ b/crates/cairo-coverage-core/src/build/filter/libfuncs.rs @@ -3,6 +3,7 @@ use cairo_lang_sierra::program::{ConcreteLibfuncLongId, Program, Statement, Stat use std::collections::{HashMap, HashSet}; use std::sync::LazyLock; +/// TODO(#235) /// This is not the best way to do this, and I'm not proud of it. /// However, it is definitely the easiest way to achieve this. /// Some functions like `store_temp` are used in many places. From 7510dca8da297602ac3406cfb6e8a663a12f717d Mon Sep 17 00:00:00 2001 From: ksew1 Date: Fri, 13 Feb 2026 13:43:09 +0100 Subject: [PATCH 3/3] Add ARCHITECTURE.md commit-id:43ecc0f0 --- ARCHITECTURE.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 ARCHITECTURE.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..f572d5b --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,82 @@ +# Architecture of Cairo Coverage + +This document outlines the architecture of the `cairo-coverage` project, detailing its structure, components, and their +interactions. + +## Overview + +The `cairo-coverage` project is structured into two main crates: + +1. `cairo-coverage`: The main command-line interface (CLI) application. +2. `cairo-coverage-core`: Contains the core logic for processing execution traces, calculating coverage, and generating + reports. + +## Crate Breakdown + +### 1. `cairo-coverage` + +This crate serves as the user-facing interface for the `cairo-coverage` tool. + +**Role**: Handles command-line argument parsing, user interaction, and dispatches commands to the `cairo-coverage-core` +library. + +### 2. `cairo-coverage-core` + +This crate encapsulates the core business logic of the coverage tool. It is responsible for loading execution traces, +analyzing Cairo programs, calculating coverage metrics, and formatting the output. + +**Role**: Performs the heavy lifting of coverage analysis. Designed to be a reusable library that can be integrated +into other tools if needed. + +**Key Modules and their Responsibilities**: + +* **`lib.rs`**: The main entry point for the core logic, containing the `run` function that orchestrates the entire + coverage generation process. It utilizes `rayon` for parallel processing to enhance performance. +* **`args`**: Defines `RunOptions`, which are specific configuration options for the core `run` function. +* **`loading/`**: Responsible for reading, deserializing, and extracting data from various input files (e.g., trace + files, Cairo programs). +* **`build/`**: Transforms the loaded raw data into intermediate data structures (`CoverageInput`) suitable for + coverage calculation. +* **`coverage/`**: Defines the data models for representing coverage information. + * `file`: Stores coverage data for individual Cairo source files. + * `function`: Stores coverage data for specific functions within files. + * `project`: Aggregates and manages coverage data for the entire project, allowing for merging and truncation. +* **`hashmap_utils/`**: Provides utility functions, notably for merging coverage data efficiently (e.g., `merge`). +* **`output/`**: Formats the processed coverage data into standard output formats. + +**High-Level Execution Flow (`run` function)**: + +1. **Initialization**: Sets up ignore patterns from `.cairo-coverage-ignore`. +2. **Load Execution Data**: Reads and deserializes execution trace files. +3. **Parallel Processing**: Each execution trace is processed in parallel: + * Filters are applied based on project configuration and ignore rules. + * Execution data is transformed into `CoverageInput`. + * Project coverage is created from the `CoverageInput`. +4. **Merge Coverage**: Coverage results from parallel processing are merged into a single project coverage report. +5. **Truncation (Optional)**: Coverage data can be optionally truncated (e.g., to report only if a line was covered + at least once). +6. **Generate Report**: The final aggregated coverage data is formatted into an LCOV string. + +## Data Flow (Conceptual) + +```mermaid +graph TD + A[Cairo Project Source Code] --> B(Scarb / Snforge Build Process) + B --> C{Cairo Program + Execution Traces}; + subgraph cairo-coverage CLI + D[User Command] --> E(Argument Parsing - clap); + E --> F(Command Dispatcher); + end + + subgraph cairo-coverage-core Library + F --> G{Core `run` Function}; + C --> G; + G --> H(Loading: Enriched Program, Execution Data); + H --> I(Build: Coverage Input, Filtering); + I --> J(Coverage Data Structures: File, Function, Project); + J --> K(Merge & Truncate Coverage); + K --> L(Output: LCOV Report); + end + + L --> M[Coverage Report LCOV file]; +``` \ No newline at end of file