Add a customizable title to Metrics reporting (#6792)

Before the PR:

$ bin/wasm-opt test/hello_world.wat --metrics
total
 [exports]      : 1       
 [funcs]        : 1       
 [globals]      : 0       
 [imports]      : 0       
 [memories]     : 1       
 [memory-data]  : 0       
 [tables]       : 0       
 [tags]         : 0       
 [total]        : 3       
 [vars]         : 0       
 Binary         : 1       
 LocalGet       : 2       

After the PR:

$ bin/wasm-opt test/hello_world.wat --metrics
Metrics
total
 [exports]      : 1       
 [funcs]        : 1       
...

Note the "Metrics" addition at the top. And the title can be customized:

$ bin/wasm-opt test/hello_world.wat --metrics=text
Metrics: text
total
 [exports]      : 1       
 [funcs]        : 1       

The custom title can be helpful when multiple invocations of metrics are used
at once, e.g. --metrics=before -O3 --metrics=after.

17 files changed, 73 insertions, 4 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d7e301ef3..1c4e369c9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,9 @@ Current Trunk
    apply to the most recent --foo pass on the commandline, if foo is a pass
    (while global pass arguments - that are not the name of a pass - remain, as
    before, global for all passes). (#6687)
+ - The Metrics pass now takes an optional argument to use as the title,
+   `--metrics=text` will show that text before the metrics. Each instance of
+   Metrics can have unique text, `--metrics=before -O3 --metrics=after`. (#6792)
  - Add C and JS APIs to control more pass options (trapsNeverHappen,
    closedWorld, generateStackIR, optimizeStackIR, and the list of skipped
    passes). (#6713)
diff --git a/src/passes/Metrics.cpp b/src/passes/Metrics.cpp
index 1778eb9bd..186d7e695 100644
--- a/src/passes/Metrics.cpp
+++ b/src/passes/Metrics.cpp
@@ -45,6 +45,13 @@ struct Metrics
   }
 
   void doWalkModule(Module* module) {
+    std::string title = getArgumentOrDefault("metrics", "");
+    std::cout << "Metrics";
+    if (!title.empty()) {
+      std::cout << ": " << title;
+    }
+    std::cout << '\n';
+
     ImportInfo imports(*module);
 
     // global things
diff --git a/src/passes/pass.cpp b/src/passes/pass.cpp
index ec6077941..3f84ee604 100644
--- a/src/passes/pass.cpp
+++ b/src/passes/pass.cpp
@@ -275,7 +275,9 @@ void PassRegistry::registerPasses() {
                createMergeSimilarFunctionsPass);
   registerPass(
     "merge-locals", "merges locals when beneficial", createMergeLocalsPass);
-  registerPass("metrics", "reports metrics", createMetricsPass);
+  registerPass("metrics",
+               "reports metrics (with an optional title, --metrics[=TITLE])",
+               createMetricsPass);
   registerPass("minify-imports",
                "minifies import names (only those, and not export names), and "
                "emits a mapping to the minified ones",
diff --git a/test/lit/help/wasm-metadce.test b/test/lit/help/wasm-metadce.test
index 66013f81a..8a2107ca7 100644
--- a/test/lit/help/wasm-metadce.test
+++ b/test/lit/help/wasm-metadce.test
@@ -251,7 +251,9 @@
 ;; CHECK-NEXT:   --merge-similar-functions                     merges similar functions when
 ;; CHECK-NEXT:                                                 benefical
 ;; CHECK-NEXT:
-;; CHECK-NEXT:   --metrics                                     reports metrics
+;; CHECK-NEXT:   --metrics                                     reports metrics (with an
+;; CHECK-NEXT:                                                 optional title,
+;; CHECK-NEXT:                                                 --metrics[=TITLE])
 ;; CHECK-NEXT:
 ;; CHECK-NEXT:   --minify-imports                              minifies import names (only
 ;; CHECK-NEXT:                                                 those, and not export names),
diff --git a/test/lit/help/wasm-opt.test b/test/lit/help/wasm-opt.test
index c89baaf4a..a48b8e303 100644
--- a/test/lit/help/wasm-opt.test
+++ b/test/lit/help/wasm-opt.test
@@ -260,7 +260,9 @@
 ;; CHECK-NEXT:   --merge-similar-functions                     merges similar functions when
 ;; CHECK-NEXT:                                                 benefical
 ;; CHECK-NEXT:
-;; CHECK-NEXT:   --metrics                                     reports metrics
+;; CHECK-NEXT:   --metrics                                     reports metrics (with an
+;; CHECK-NEXT:                                                 optional title,
+;; CHECK-NEXT:                                                 --metrics[=TITLE])
 ;; CHECK-NEXT:
 ;; CHECK-NEXT:   --minify-imports                              minifies import names (only
 ;; CHECK-NEXT:                                                 those, and not export names),
diff --git a/test/lit/help/wasm2js.test b/test/lit/help/wasm2js.test
index 45bef7d73..0b87ad0aa 100644
--- a/test/lit/help/wasm2js.test
+++ b/test/lit/help/wasm2js.test
@@ -214,7 +214,9 @@
 ;; CHECK-NEXT:   --merge-similar-functions                     merges similar functions when
 ;; CHECK-NEXT:                                                 benefical
 ;; CHECK-NEXT:
-;; CHECK-NEXT:   --metrics                                     reports metrics
+;; CHECK-NEXT:   --metrics                                     reports metrics (with an
+;; CHECK-NEXT:                                                 optional title,
+;; CHECK-NEXT:                                                 --metrics[=TITLE])
 ;; CHECK-NEXT:
 ;; CHECK-NEXT:   --minify-imports                              minifies import names (only
 ;; CHECK-NEXT:                                                 those, and not export names),
diff --git a/test/lit/passes/metrics.wast b/test/lit/passes/metrics.wast
new file mode 100644
index 000000000..5a210ae6d
--- /dev/null
+++ b/test/lit/passes/metrics.wast
@@ -0,0 +1,30 @@
+;; Test that we can pass an optional title to metrics instances.
+;;
+;; RUN: wasm-opt %s --metrics --metrics=second --remove-unused-module-elements --metrics=third --metrics -q | filecheck %s
+;;
+;; The number of functions decreases to 0 after --remove-unused-module-elements,
+;; showing that we display the proper metrics at each point in time.
+;;
+;; CHECK:      Metrics
+;; CHECK-NEXT: total
+;; CHECK-NEXT:  [exports]      : 0
+;; CHECK-NEXT:  [funcs]        : 1
+;;
+;; CHECK:      Metrics: second
+;; CHECK-NEXT: total
+;; CHECK-NEXT:  [exports]      : 0
+;; CHECK-NEXT:  [funcs]        : 1
+;;
+;; CHECK:      Metrics: third
+;; CHECK-NEXT: total
+;; CHECK-NEXT:  [exports]      : 0
+;; CHECK-NEXT:  [funcs]        : 0             -1
+;;
+;; CHECK:      Metrics
+;; CHECK-NEXT: total
+;; CHECK-NEXT:  [exports]      : 0
+;; CHECK-NEXT:  [funcs]        : 0
+
+(module
+  (func $foo)
+)
diff --git a/test/passes/O3_low-memory-unused_metrics.txt b/test/passes/O3_low-memory-unused_metrics.txt
index fd9245adc..8806e9a04 100644
--- a/test/passes/O3_low-memory-unused_metrics.txt
+++ b/test/passes/O3_low-memory-unused_metrics.txt
@@ -1,3 +1,4 @@
+Metrics
 total
  [exports]      : 1       
  [funcs]        : 1       
diff --git a/test/passes/converge_O3_metrics.bin.txt b/test/passes/converge_O3_metrics.bin.txt
index 312e67fe7..712172cc7 100644
--- a/test/passes/converge_O3_metrics.bin.txt
+++ b/test/passes/converge_O3_metrics.bin.txt
@@ -1,3 +1,4 @@
+Metrics
 total
  [exports]      : 2       
  [funcs]        : 6       
@@ -231,6 +232,7 @@ total
   (i32.const 0)
  )
 )
+Metrics
 total
  [exports]      : 2       
  [funcs]        : 6       
@@ -457,6 +459,7 @@ total
   (i32.const 0)
  )
 )
+Metrics
 total
  [exports]      : 2       
  [funcs]        : 6       
diff --git a/test/passes/func-metrics.txt b/test/passes/func-metrics.txt
index afd6afe07..b61e8146e 100644
--- a/test/passes/func-metrics.txt
+++ b/test/passes/func-metrics.txt
@@ -1,3 +1,4 @@
+Metrics
 global
  [exports]      : 0       
  [funcs]        : 3       
@@ -106,6 +107,7 @@ func: ifs
   )
  )
 )
+Metrics
 global
  [exports]      : 0       
  [funcs]        : 0       
@@ -117,6 +119,7 @@ global
  [total]        : 0       
 (module
 )
+Metrics
 global
  [exports]      : 2       
  [funcs]        : 3       
@@ -194,6 +197,7 @@ export: b (func_b)
   (call $waka)
  )
 )
+Metrics
 global
  [exports]      : 1       
  [funcs]        : 1       
@@ -228,6 +232,7 @@ start: func_a
   (call $waka)
  )
 )
+Metrics
 global
  [exports]      : 0       
  [funcs]        : 1       
@@ -258,6 +263,7 @@ start: func_a
   (call $waka)
  )
 )
+Metrics
 global
  [exports]      : 1       
  [funcs]        : 1       
diff --git a/test/passes/fuzz_metrics_noprint.bin.txt b/test/passes/fuzz_metrics_noprint.bin.txt
index c5dab17e7..2f1719633 100644
--- a/test/passes/fuzz_metrics_noprint.bin.txt
+++ b/test/passes/fuzz_metrics_noprint.bin.txt
@@ -1,3 +1,4 @@
+Metrics
 total
  [exports]      : 23      
  [funcs]        : 34      
diff --git a/test/passes/metrics_all-features.txt b/test/passes/metrics_all-features.txt
index 2fcf29257..a5e80db45 100644
--- a/test/passes/metrics_all-features.txt
+++ b/test/passes/metrics_all-features.txt
@@ -1,3 +1,4 @@
+Metrics
 total
  [exports]      : 0       
  [funcs]        : 1       
@@ -80,6 +81,7 @@ total
   )
  )
 )
+Metrics
 total
  [exports]      : 0       
  [funcs]        : 0       
diff --git a/test/passes/metrics_strip-debug_metrics.bin.txt b/test/passes/metrics_strip-debug_metrics.bin.txt
index ef1b5c013..848db9e32 100644
--- a/test/passes/metrics_strip-debug_metrics.bin.txt
+++ b/test/passes/metrics_strip-debug_metrics.bin.txt
@@ -1,3 +1,4 @@
+Metrics
 total
  [exports]      : 1       
  [funcs]        : 1       
@@ -9,6 +10,7 @@ total
  [total]        : 1       
  [vars]         : 0       
  Nop            : 1       
+Metrics
 total
  [exports]      : 1       
  [funcs]        : 1       
diff --git a/test/passes/metrics_strip-producers_metrics.bin.txt b/test/passes/metrics_strip-producers_metrics.bin.txt
index a983af3a9..65d6bd6a8 100644
--- a/test/passes/metrics_strip-producers_metrics.bin.txt
+++ b/test/passes/metrics_strip-producers_metrics.bin.txt
@@ -1,3 +1,4 @@
+Metrics
 total
  [exports]      : 1       
  [funcs]        : 1       
@@ -9,6 +10,7 @@ total
  [total]        : 1       
  [vars]         : 0       
  Nop            : 1       
+Metrics
 total
  [exports]      : 1       
  [funcs]        : 1       
diff --git a/test/passes/print_g_metrics.bin.txt b/test/passes/print_g_metrics.bin.txt
index e5ac1edae..2acec546f 100644
--- a/test/passes/print_g_metrics.bin.txt
+++ b/test/passes/print_g_metrics.bin.txt
@@ -66,6 +66,7 @@
   (nop)
  )
 )
+Metrics
 total
  [exports]      : 3       
  [funcs]        : 3       
diff --git a/test/passes/sparse_matrix_liveness.bin.txt b/test/passes/sparse_matrix_liveness.bin.txt
index 7e9429545..62f7582c8 100644
--- a/test/passes/sparse_matrix_liveness.bin.txt
+++ b/test/passes/sparse_matrix_liveness.bin.txt
@@ -1,3 +1,4 @@
+Metrics
 total
  [exports]      : 1       
  [funcs]        : 1       
@@ -12,6 +13,7 @@ total
  Const          : 1       
  LocalGet       : 1       
  LocalSet       : 1       
+Metrics
 total
  [exports]      : 1       
  [funcs]        : 1       
diff --git a/test/passes/translate-to-fuzz_all-features_metrics_noprint.txt b/test/passes/translate-to-fuzz_all-features_metrics_noprint.txt
index 6db0f908d..07afaa7eb 100644
--- a/test/passes/translate-to-fuzz_all-features_metrics_noprint.txt
+++ b/test/passes/translate-to-fuzz_all-features_metrics_noprint.txt
@@ -1,3 +1,4 @@
+Metrics
 total
  [exports]      : 5       
  [funcs]        : 9