src: add --print-pending-tla flag

Author: joyeecheung

doc/api/cli.md

@@ -1578,6 +1578,17 @@ changes:
 
 Identical to `-e` but prints the result.
 
+### `--print-pending-tla`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Print pending top-level await in the graph.
+
+<!-- TODO(joyeecheung): do a PR separately for this flag because we can also
+fix https://github.com/nodejs/node/issues/42868 with it -->
+
 ### `--prof`
 
 <!-- YAML
@@ -2556,6 +2567,7 @@ Node.js options that are allowed are:
 * `--policy-integrity`
 * `--preserve-symlinks-main`
 * `--preserve-symlinks`
+* `--print-pending-tla`
 * `--prof-process`
 * `--redirect-warnings`
 * `--report-compact`

src/node_options.cc

@@ -352,6 +352,13 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             "ES module syntax, try again to evaluate them as ES modules",
             &EnvironmentOptions::detect_module,
             kAllowedInEnvvar);
+  AddOption("--print-pending-tla",
+            "Print pending top-level await. If --experimental-require-module "
+            "is true, evaluate asynchronous graphs loaded by `require()` but "
+            "do not run the microtasks, in order to to find and print "
+            "top-level await in the graph",
+            &EnvironmentOptions::print_pending_tla,
+            kAllowedInEnvvar);
   AddOption("--diagnostic-dir",
             "set dir for all output files"
             " (default: current working directory)",

src/node_options.h

@@ -105,6 +105,7 @@ class EnvironmentOptions : public Options {
   bool abort_on_uncaught_exception = false;
   std::vector<std::string> conditions;
   bool detect_module = false;
+  bool print_pending_tla = false;
   std::string dns_result_order;
   bool enable_source_maps = false;
   bool experimental_fetch = true;