Categorize to stable and unstable

CHANGELOG.md

@@ -8,12 +8,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 #### Added
+
 - warning if the current scarb version doesn't support not including macros in the coverage report
+- `--unstable` flag to enable unstable features. Read more about
+  it [here](./README.md#coverage-across-different-scarb-versions)
 
 #### Changed
-- macros are now by default included in the coverage report. If you want to exclude them, use the `--include` without the
-  `macros` option (can also have empty value)
-- by default, the hit count of the lines will be truncated to 1. This can be changed with the `--no-truncation` flag
+
+- macros are now by default included in the coverage report. If you want to exclude them, use the `--include` without
+  the `macros` option (can also have empty value). This is due to a new stability policy. Read more about
+  it [here](./README.md#coverage-across-different-scarb-versions)
+- by default, the hit count of the lines will be truncated to 1. This can be changed with the `--no-truncation` flag.
+  This is due to a new stability policy. Read more about it [here](./README.md#coverage-across-different-scarb-versions)
 
 ## [0.4.0] - 2025-01-03
 

README.md

@@ -69,6 +69,19 @@ Using the `--help` flag with any command will display additional information abo
 cairo-coverage clean  --help
 ```
 
+### Coverage Across Different Scarb Versions
+
+`cairo-coverage` relies heavily on `scarb` and the internal workings of the `cairo` compiler, which can lead to variations in behavior depending on the `scarb` version used.
+
+To ensure consistency in coverage reports across different versions of `scarb`, we have categorized features into **stable** and **unstable**:
+
+- **Stable features** provide consistent results across all versions of `scarb`.
+- **Unstable features** may produce different results depending on the `scarb` version.
+
+A feature is considered **stable** if it produces the same results across all minor versions of `scarb` from `2.8.*` onward, using the latest patch version.
+
+To enable unstable features, use the `--unstable` flag.
+
 ### `.cairo-coverage-ignore` File
 
 You can create a `.cairo-coverage-ignore` file in the root of your project to specify the files or directories that you

crates/cairo-coverage/src/args/run.rs

@@ -14,13 +14,17 @@ pub struct RunArgs {
     pub output_path: Utf8PathBuf,
 
     /// Include additional components in the coverage report.
-    #[arg(long, short, num_args = 0.., default_value = "macros")]
+    #[arg(long, short, num_args = 0.., default_value = "macros", requires = "unstable")]
     pub include: Vec<IncludedComponent>,
 
     /// If set, the hit count of the lines will not be truncated to 1.
-    #[arg(long)]
+    #[arg(long, requires = "unstable")]
     pub no_truncation: bool,
 
+    /// If set, the unstable features are enabled.
+    #[arg(long)]
+    pub unstable: bool,
+
     /// Path to the project directory. If not provided, the project directory is inferred using `scarb metadata`.
     #[arg(value_parser = parse_project_path, long)]
     pub project_path: Option<Utf8PathBuf>,

crates/cairo-coverage/src/commands/run.rs

@@ -15,6 +15,7 @@ pub fn run(
         output_path,
         trace_files,
         no_truncation,
+        unstable: _,
     }: RunArgs,
 ) -> Result<()> {
     let metadata = scarb_metadata()?;

crates/cairo-coverage/tests/e2e/general.rs

@@ -12,7 +12,7 @@ fn simple() {
 #[cfg(feature = "allows-excluding-macros")]
 fn simple_with_tests() {
     TestProject::new("simple")
-        .coverage_args(&["--include", "test-functions"])
+        .coverage_args(&["--unstable", "--include", "test-functions"])
         .run()
         .output_same_as_in_file("simple_with_tests.lcov");
 }
@@ -63,7 +63,7 @@ fn macros() {
 #[cfg(feature = "allows-excluding-macros")]
 fn macros_not_included() {
     TestProject::new("macros")
-        .coverage_args(&["--include"])
+        .coverage_args(&["--unstable", "--include"])
         .run_without_genhtml()
         .assert_empty_output();
 }
@@ -79,7 +79,7 @@ fn snforge_template() {
 #[cfg(feature = "allows-excluding-macros")]
 fn snforge_template_macros_not_included() {
     TestProject::new("snforge_template")
-        .coverage_args(&["--include"])
+        .coverage_args(&["--unstable", "--include"])
         .run()
         .output_same_as_in_file("snforge_template_macros_not_included.lcov");
 }