[analysis] Add a new iterable CFG utility (#5712)

Add a new "analysis" source directory that will contain the source for a new
static program analysis framework. To start the framework, add a CFG utility
that provides convenient iterators for iterating through the basic blocks of the
CFG as well as the predecessors, successors, and contents of each block.

The new CFGs are constructed using the existing CFGWalker, but they are
different in that the new utility is meant to provide a usable representation of
a CFG whereas CFGWalker is meant to allow collecting arbitrary information about
each basic block in a CFG.

For testing and debugging purposes, add `print` methods to CFGs and basic
blocks. This requires exposing the ability to print expression contents
excluding children, which was something we previously did only for StackIR.

Also add a new gtest file with a test for constructing and printing a CFG. The
test reveals some strange properties of the current CFG construction, including
empty blocks and strange placement of `loop` instructions, but fixing these
problems is left as future work.

1 files changed, 79 insertions, 0 deletions

diff --git a/src/analysis/cfg.h b/src/analysis/cfg.h
new file mode 100644
index 000000000..3b980f410
--- /dev/null
+++ b/src/analysis/cfg.h
@@ -0,0 +1,79 @@
+/*
+ * Copyright 2023 WebAssembly Community Group participants
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// A generic CFG / basic block utility. Unlike the utilities in src/cfg/, this
+// is a generic representation of a CFG rather than a generic builder of
+// CFG-like objects. It lives here in src/analysis/ because it is primarily
+// meant for use in the static analysis framework. Other Binaryen code will find
+// it more idiomatic to use the utilities in src/cfg/.
+
+#ifndef wasm_analysis_cfg_h
+#define wasm_analysis_cfg_h
+
+#include <iostream>
+#include <vector>
+
+#include "wasm.h"
+
+namespace wasm::analysis {
+
+struct BasicBlock;
+
+struct CFG {
+  // Iterate through basic blocks.
+  using iterator = std::vector<BasicBlock>::const_iterator;
+  iterator begin() const { return blocks.cbegin(); }
+  iterator end() const { return blocks.cend(); }
+  size_t size() const { return blocks.size(); }
+
+  static CFG fromFunction(Function* func);
+
+  void print(std::ostream& os, Module* wasm = nullptr) const;
+
+private:
+  std::vector<BasicBlock> blocks;
+  friend BasicBlock;
+};
+
+struct BasicBlock {
+  using iterator = std::vector<Expression*>::const_iterator;
+
+  // Iterate through instructions.
+  iterator begin() const { return insts.cbegin(); }
+  iterator end() const { return insts.cend(); }
+  size_t size() const { return insts.size(); }
+
+  // Iterables for predecessor and successor blocks.
+  struct Predecessors;
+  struct Successors;
+  Predecessors preds() const;
+  Successors succs() const;
+
+  void print(std::ostream& os, Module* wasm = nullptr, size_t start = 0) const;
+
+private:
+  Index index;
+  std::vector<Expression*> insts;
+  std::vector<BasicBlock*> predecessors;
+  std::vector<BasicBlock*> successors;
+  friend CFG;
+};
+
+} // namespace wasm::analysis
+
+#include "cfg-impl.h"
+
+#endif // wasm_analysis_cfg_h