[move] Add lcov test coverage emitter for Move code (#21723)

## Description 

This adds support generating LCOV information based on Move unit tests.

It does this by adding a new flag to the `coverage` command. So to get
LCOV test coverage data for Move unit tests you would do

```
sui move test --trace-execution
sui move coverage lcov
```

This would generate an `lcov.info` file in your package root which you
can then use for tools that use LCOV data (e.g., coverage gutters and
the like).

## Test plan 

CI + added a test the existing tracing test to test that we can generate
the lcov information.

Author: tzakian

Cargo.lock

@@ -141,6 +141,7 @@ z3tracer = "0.8.0"
 inline_colorization = "0.1.6"
 insta = "1.42.0"
 zstd = "0.13.2"
+lcov = "0.8.1"
 
 bytecode-interpreter-crypto = { path = "crates/bytecode-interpreter-crypto" }
 enum-compat-util = { path = "crates/enum-compat-util" }

external-crates/move/Cargo.lock

@@ -44,6 +44,7 @@ move-symbol-pool.workspace = true
 move-unit-test.workspace = true
 move-bytecode-viewer.workspace = true
 move-model-2.workspace = true
+move-trace-format.workspace = true
 
 [dev-dependencies]
 datatest-stable.workspace = true

external-crates/move/Cargo.toml

@@ -5,12 +5,19 @@ use super::reroot_path;
 use clap::*;
 use move_compiler::compiled_unit::NamedCompiledModule;
 use move_coverage::{
-    coverage_map::CoverageMap, format_csv_summary, format_human_summary,
-    source_coverage::SourceCoverageBuilder, summary::summarize_inst_cov,
+    coverage_map::CoverageMap, differential_coverage, format_csv_summary, format_human_summary,
+    lcov, source_coverage::SourceCoverageBuilder, summary::summarize_inst_cov,
 };
 use move_disassembler::disassembler::Disassembler;
 use move_package::BuildConfig;
-use std::path::Path;
+use move_trace_format::format::MoveTraceReader;
+use std::{
+    fs::File,
+    path::{Path, PathBuf},
+};
+
+const COVERAGE_FILE_NAME: &str = "lcov.info";
+const DIFFERENTIAL: &str = "diff";
 
 #[derive(Parser)]
 pub enum CoverageSummaryOptions {
@@ -36,6 +43,19 @@ pub enum CoverageSummaryOptions {
         #[clap(long = "module")]
         module_name: String,
     },
+    #[clap(name = "lcov")]
+    Lcov {
+        /// Compute differential coverage for the provided test name. Lines that are hit by this
+        /// test only will show as covered, and lines that are hit by both this test and all other
+        /// tests will show as "uncovered". Otherwise lines are not annotated with coverage
+        /// information.
+        #[clap(long = "differential-test")]
+        differential: Option<String>,
+        /// Compute coverage for the provided test name. Only this test will contribute to the
+        /// coverage calculation.
+        #[clap(long = "only-test", conflicts_with = "differential")]
+        test: Option<String>,
+    },
 }
 
 /// Inspect test coverage for this package. A previous test run with the `--coverage` flag must
@@ -50,9 +70,16 @@ pub struct Coverage {
 impl Coverage {
     pub fn execute(self, path: Option<&Path>, config: BuildConfig) -> anyhow::Result<()> {
         let path = reroot_path(path)?;
-        let coverage_map = CoverageMap::from_binary_file(path.join(".coverage_map.mvcov"))?;
+
+        // We treat lcov-format coverage differently because it requires traces to be present, and
+        // we don't use the old trace format for it.
+        if let CoverageSummaryOptions::Lcov { differential, test } = self.options {
+            return Self::output_lcov_coverage(path, config, differential, test);
+        }
+
         let package = config.compile_package(&path, &mut Vec::new())?;
         let modules = package.root_modules().map(|unit| &unit.unit.module);
+        let coverage_map = CoverageMap::from_binary_file(path.join(".coverage_map.mvcov"))?;
         match self.options {
             CoverageSummaryOptions::Source { module_name } => {
                 let unit = package.get_module_by_name_from_root(&module_name)?;
@@ -95,7 +122,119 @@ impl Coverage {
                 disassembler.add_coverage_map(coverage_map.to_unified_exec_map());
                 println!("{}", disassembler.disassemble()?);
             }
+            CoverageSummaryOptions::Lcov { .. } => {
+                unreachable!()
+            }
         }
         Ok(())
     }
+
+    pub fn output_lcov_coverage(
+        path: PathBuf,
+        mut config: BuildConfig,
+        differential: Option<String>,
+        test: Option<String>,
+    ) -> anyhow::Result<()> {
+        // Make sure we always compile the package in test mode so we get correct source maps.
+        config.test_mode = true;
+        let package = config.compile_package(&path, &mut Vec::new())?;
+        let units: Vec<_> = package
+            .all_modules()
+            .cloned()
+            .map(|unit| (unit.unit, unit.source_path))
+            .collect();
+        let traces = path.join("traces");
+        let sanitize_name = |s: &str| s.replace("::", "__");
+        let trace_of_test = |test_name: &str| {
+            let trace_substr_name = format!("{}.", sanitize_name(test_name));
+            std::fs::read_dir(&traces)?
+                .filter_map(|entry| {
+                    let entry = entry.unwrap();
+                    let path = entry.path();
+                    if path.is_file()
+                        && path
+                            .file_name()
+                            .unwrap()
+                            .to_str()
+                            .unwrap()
+                            .contains(&trace_substr_name)
+                    {
+                        Some(path)
+                    } else {
+                        None
+                    }
+                })
+            .next()
+            .ok_or_else(|| {
+                anyhow::anyhow!(
+                    "No trace found for test {}. Please run with `--coverage` to generate traces.",
+                    test_name
+                )
+            })
+        };
+
+        if let Some(test_name) = test {
+            let mut coverage = lcov::PackageRecordKeeper::new(units, package.file_map.clone());
+            let trace_path = trace_of_test(&test_name)?;
+            let file = File::open(&trace_path)?;
+            let move_trace_reader = MoveTraceReader::new(file)?;
+            coverage.calculate_coverage(move_trace_reader);
+            std::fs::write(
+                &path.join(format!(
+                    "{}.{COVERAGE_FILE_NAME}",
+                    sanitize_name(&test_name)
+                )),
+                coverage.lcov_record_string(),
+            )?;
+        } else {
+            let mut coverage =
+                lcov::PackageRecordKeeper::new(units.clone(), package.file_map.clone());
+            let differential_test_path = differential
+                .as_ref()
+                .map(|s| trace_of_test(s))
+                .transpose()?;
+
+            for entry in std::fs::read_dir(&traces)? {
+                let entry = entry?;
+                let path = entry.path();
+                if path.is_file()
+                    && differential_test_path
+                        .as_ref()
+                        .is_none_or(|diff_path| diff_path != &path)
+                {
+                    let file = File::open(&path)?;
+                    let move_trace_reader = MoveTraceReader::new(file)?;
+                    coverage.calculate_coverage(move_trace_reader);
+                }
+            }
+
+            if let Some(differential_test_name) = differential {
+                let trace_path =
+                    differential_test_path.expect("Differential test path is already computed");
+                let file = File::open(&trace_path)?;
+                let move_trace_reader = MoveTraceReader::new(file)?;
+                let mut test_coverage =
+                    lcov::PackageRecordKeeper::new(units, package.file_map.clone());
+                test_coverage.calculate_coverage(move_trace_reader);
+
+                let differential_string =
+                    differential_coverage::differential_report(&coverage, &test_coverage)?;
+
+                std::fs::write(
+                    &path.join(format!(
+                        "{}.{DIFFERENTIAL}.{COVERAGE_FILE_NAME}",
+                        sanitize_name(&differential_test_name)
+                    )),
+                    differential_string,
+                )?;
+            } else {
+                std::fs::write(
+                    &path.join(COVERAGE_FILE_NAME),
+                    coverage.lcov_record_string(),
+                )?;
+            }
+        };
+
+        Ok(())
+    }
 }

external-crates/move/crates/move-cli/Cargo.toml

@@ -243,8 +243,8 @@ pub fn run_one(
             let cmd_output = command.output()?;
 
             writeln!(&mut output, "External Command `{}`:", external_cmd)?;
-            output += std::str::from_utf8(&cmd_output.stdout)?;
-            output += std::str::from_utf8(&cmd_output.stderr)?;
+            output += std::str::from_utf8(cmd_output.stdout.trim_ascii_start())?;
+            output += std::str::from_utf8(cmd_output.stderr.trim_ascii_start())?;
 
             continue;
         }

external-crates/move/crates/move-cli/src/base/coverage.rs

@@ -0,0 +1,2 @@
+traces
+*lcov.info

external-crates/move/crates/move-cli/src/sandbox/commands/test.rs

@@ -6,6 +6,8 @@ Running Move unit tests
 [ PASS    ] 0x1::calls::test_call_return_order
 [ PASS    ] 0x1::calls::test_complex_nested_calls
 [ PASS    ] 0x1::calls::test_return_order
+[ PASS    ] 0x1::differential_test::f1
+[ PASS    ] 0x1::differential_test::f21
 [ PASS    ] 0x1::errors::aborter
 [ PASS    ] 0x1::errors::bad_cast
 [ PASS    ] 0x1::errors::div_0
@@ -26,5 +28,16 @@ Running Move unit tests
 [ PASS    ] 0x1::references::test_struct_borrow
 [ PASS    ] 0x1::references::test_vector_mut_borrow
 [ PASS    ] 0x1::references::test_vector_mut_borrow_pop
-Test result: OK. Total tests: 24; passed: 24; failed: 0
+Test result: OK. Total tests: 26; passed: 26; failed: 0
 External Command `diff -qr traces saved_traces`:
+Only in traces: 0x1__differential_test__f1.json.zst
+Only in traces: 0x1__differential_test__f21.json.zst
+Command `coverage lcov`:
+External Command `wc -l lcov.info`:
+6012 lcov.info
+Command `coverage lcov --only-test f21`:
+External Command `wc -l f21.lcov.info`:
+5828 f21.lcov.info
+Command `coverage lcov --differential-test f21`:
+External Command `wc -l f21.diff.lcov.info`:
+26 f21.diff.lcov.info

external-crates/move/crates/move-cli/tests/tracing_tests/tracing-unit-tests/.gitignore

@@ -1,2 +1,11 @@
 test -t 1 --trace-execution
 > diff -qr traces saved_traces
+
+coverage lcov
+> wc -l lcov.info
+
+coverage lcov --only-test f21
+> wc -l f21.lcov.info
+
+coverage lcov --differential-test f21
+> wc -l f21.diff.lcov.info

external-crates/move/crates/move-cli/tests/tracing_tests/tracing-unit-tests/args.exp

@@ -0,0 +1,26 @@
+module 0x1::differential_test;
+
+#[test]
+fun f1() {
+    f(0);
+}
+
+#[test]
+fun f21() {
+    f(21);
+}
+
+public fun f(x: u64): u64 {
+    let x = x + 1;
+    call(x);
+    if (x > 10) {
+        1
+    } else {
+        0
+    }
+}
+
+
+public fun call(x: u64) {
+    x + 1;
+}