Implement panic expression (#7073)

## Description

This PR introduces the `panic` expression to the language, as defined in
the [ABI Errors
RFC](https://github.com/FuelLabs/sway-rfcs/blob/master/rfcs/0014-abi-errors.md#panic).

The `panic` expression can be used without arguments, or accept an
argument that implements the `std::marker::Error` trait. The `Error`
trait is implemented by the compiler for the unit `()`, string slices,
and `#[error_type]` enums.

Using the `panic` expression without arguments gives the symetry with
the `return` expression and acts in the same way as having unit as an
argument.

```
panic;
panic ();
panic "This is some error.";
panic Errors::SomeError(42);
```

Panicking without an argument or with unit as argument is discouraged to
use. In the upcoming PR that finalizes the ABI errors feature, we will
emit a warning if the `panic` is used without arguments or with unit as
argument.

`panic` expression is available in all program kinds. In predicates it
currently compiles only to revert. Once `__dbg` intrinsic is
implemented, we can consider compiling to it in predicates. In the
upcoming PR, the `error_codes` entry in the ABI JSON will be available
for all program kinds.

The dead code analysis for the `panic` expression is implemented in the
straightforward way, following the current approach of connecting
reverts to the exit node. This will be revisted in a separate PR,
together with the open TODOs in the DCA implementation of `Return`.
Essentially, we want reverting/panicking to connect to program exit and
implicit returns to the exit node.

Additionally, the PR:
- extends `forc test` CLI attributes with `--revert-codes` that prints
revert codes even if tests are successful but revert.
- updates outdated "Logs Inside Tests" chapter in the documentation on
unit testing.
- extends the snapshot testing infrastructure to support `forc test` in
snapshot tests.
- fixes #7072.

Partially addresses #6765.

## Breaking Change

`panic` is a new reserved keyword. Once the `error_type` feature becomes
integrated, compiling any existing code containing a "panic" as an
identifier will result in an "Identifiers cannot be a reserved keyword."
error.

In this PR, `panic` keyword is hidden behind the `error_type` feature
flag. This prevents existing code from breaking, unless opted-in.

Note that, although being behind a feature flag, `panic` cannot be used
in conditional compilation, means in combination with the
`#[cfg(experimental_error_type = true/false)]`. The reason is that `cfg`
evaluation happens after parsing, and we can either parse `panic` as a
keyword or identifier during the parsing, because we cannot distinguish
ambiguous cases like `panic;` or just `panic`.

This limitation means, that introducing `panic` to `std` can be done
only once the `error_type` feature is fully integrated. In practice,
this is not a serious limitation, because introducing `panic` in `std`
would anyhow, due to effort and design decisions, happen after the
feature is integrated.

We will provide a migration for this breaking change that will migrate
the existing "panic" identifiers to "r#panic".

## Checklist

- [x] I have linked to any relevant issues.
- [x] I have commented my code, particularly in hard-to-understand
areas.
- [x] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [ ] If my change requires substantial documentation changes, I have
[requested support from the DevRel
team](https://github.com/FuelLabs/devrel-requests/issues/new/choose)
- [x] I have added tests that prove my fix is effective or that my
feature works.
- [x] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [x] I have done my best to ensure that my PR adheres to [the Fuel Labs
Code Review
Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md).
- [x] I have requested a review from the relevant team or maintainers.

Author: ironcev

docs/book/src/testing/unit-testing.md

@@ -71,9 +71,16 @@ fn test_meaning_of_life() {
 
 Tests with `#[test(should_revert)]` are considered to be passing if they are reverting.
 
+Revert codes are not shown by default in passing tests that have `should_revert`. To see revert codes, use the `--revert-codes` flag, `forc test --revert-codes`:
+
+```console
+      test test_meaning_of_life ... ok (23.099µs, 0 gas)
+Revert code: ffffffffffff0004
+```
+
 ## Calling Contracts
 
-Unit tests can call contract functions an example for such calls can be seen below.
+Unit tests can call contract functions. An example for such calls can be seen below.
 
 ```sway
 contract;
@@ -96,7 +103,7 @@ To test the `test_function()`, a unit test like the following can be written.
 fn test_success() {
     let caller = abi(MyContract, CONTRACT_ID);
     let result = caller.test_function {}();
-    assert(result == true)
+    assert(result == true);
 }
 ```
 
@@ -107,7 +114,7 @@ It is also possible to test failure with contract calls as well.
 fn test_fail() {
     let caller = abi(MyContract, CONTRACT_ID);
     let result = caller.test_function {}();
-    assert(result == false)
+    assert(result == false);
 }
 ```
 
@@ -154,37 +161,58 @@ fn main() {}
 
 #[test]
 fn test_fn() {
-let a = 10;
+    let a = 10;
     log(a);
     let b = 30;
     log(b);
-    assert_eq(a, 10)
-    assert_eq(b, 30)
+    assert_eq(a, 10);
+    assert_eq(b, 30);
 }
 ```
 
-The example shown above is logging two different variables, `a` and `b` and their values are `10` and `30`, respectively. Without log decoding printed log for this test with `forc test --logs` (`--logs` flag is required to see the logs for this example since the test is passing. Logs are silenced by default in passing tests, and can be enabled using the `--logs` flag.):
+The above example shows a passing test that is logging two different variables, `a` and `b`, and their values are `10` and `30`, respectively. Logs are silenced by default in passing tests, and can be enabled using the `--logs` flag, `forc test --logs`:
 
 ```console
-Finished debug [unoptimized + fuel] target(s) in 5.23s
-      Bytecode hash: 0x1cb1edc031691c5c08b50fd0f07b02431848ab81b325b72eb3fd233c67d6b548
-   Running 1 test, filtered 0 tests
-      test test_fn ... ok (38.875µs, 232 gas)
-[{"LogData":{"data":"000000000000000a","digest":"8d85f8467240628a94819b26bee26e3a9b2804334c63482deacec8d64ab4e1e7","id":"0000000000000000000000000000000000000000000000000000000000000000","is":10368,"len":8,"pc":11032,"ptr":67107840,"ra":0,"rb":0}},{"LogData":{"data":"000000000000001e","digest":"48a97e421546f8d4cae1cf88c51a459a8c10a88442eed63643dd263cef880c1c","id":"0000000000000000000000000000000000000000000000000000000000000000","is":10368,"len":8,"pc":11516,"ptr":67106816,"ra":0,"rb":1}}]
+     Running 1 test, filtered 0 tests
+      test test_fn ... ok (58.842µs, 0 gas)
+Decoded log value: 10, log rb: 1515152261580153489
+Decoded log value: 30, log rb: 1515152261580153489
 ```
 
-This is not very easy to understand, it is possible to decode these logs with `--decode` flag, executing `forc test --logs --decode`:
+The `--logs` flag prints decoded log values. If you want to see pretty-printed raw log receipts you can use the `--raw-logs --pretty` flags, `forc test --raw-logs --pretty`:
 
 ```console
-Finished debug [unoptimized + fuel] target(s) in 5.23s
-      Bytecode hash: 0x1cb1edc031691c5c08b50fd0f07b02431848ab81b325b72eb3fd233c67d6b548
-   Running 1 test, filtered 0 tests
-      test test_fn ... ok (38.875µs, 232 gas)
-Decoded log value: 10, log rb: 0
-Decoded log value: 30, log rb: 1
+      test test_fn ... ok (54.042µs, 0 gas)
+Raw logs:
+[
+  {
+    "LogData": {
+      "data": "000000000000000a",
+      "digest": "8d85f8467240628a94819b26bee26e3a9b2804334c63482deacec8d64ab4e1e7",
+      "id": "0000000000000000000000000000000000000000000000000000000000000000",
+      "is": 10368,
+      "len": 8,
+      "pc": 11212,
+      "ptr": 67107840,
+      "ra": 0,
+      "rb": 1515152261580153489
+    }
+  },
+  {
+    "LogData": {
+      "data": "000000000000001e",
+      "digest": "48a97e421546f8d4cae1cf88c51a459a8c10a88442eed63643dd263cef880c1c",
+      "id": "0000000000000000000000000000000000000000000000000000000000000000",
+      "is": 10368,
+      "len": 8,
+      "pc": 11212,
+      "ptr": 67106816,
+      "ra": 0,
+      "rb": 1515152261580153489
+    }
+  }
+]
 ```
 
-As it can be seen, the values are human readable and easier to understand which makes debugging much more easier.
-
-**Note**: This is an experimental feature and we are actively working on reporting variable names next to their values.
+The `--logs` and `--raw-logs` flags can be combined to print both the decoded and raw logs.
 <!-- unit_test_log::example::end -->

forc-plugins/forc-migrate/src/visiting/mod.rs

@@ -634,6 +634,9 @@ impl __ProgramVisitor {
                     Self::visit_expr(ctx, lexed_returned.__as_ref(), ty_returned, visitor, output)?;
                 }
             }
+            Expr::Panic { expr_opt: _, .. } => {
+                // TODO: Implement visiting `panic`.
+            }
             Expr::If(if_expr) => {
                 Self::visit_if(ctx, if_expr, ty_expr, visitor, output)?;
             }

forc/src/cli/commands/test.rs

@@ -71,6 +71,9 @@ pub struct TestPrintOpts {
     /// Print the raw logs for tests.
     #[clap(long)]
     pub raw_logs: bool,
+    /// Print the revert codes for tests.
+    #[clap(long)]
+    pub revert_codes: bool,
 }
 
 pub(crate) fn exec(cmd: Command) -> ForcResult<()> {
@@ -171,11 +174,19 @@ fn print_tested_pkg(pkg: &TestedPackage, test_print_opts: &TestPrintOpts) -> For
             }
         }
 
+        // If raw logs are enabled, print them.
         if test_print_opts.raw_logs {
             let formatted_logs = format_log_receipts(logs, test_print_opts.pretty_print)?;
             info!("Raw logs:\n{}", formatted_logs);
         }
 
+        // If revert codes are enabled, print them.
+        if test_print_opts.revert_codes {
+            if let Some(revert_code) = test.revert_code() {
+                info!("Revert code: {revert_code:x}");
+            }
+        }
+
         // If the test is failing, save the test result for printing the details later on.
         if !test_passed {
             failed_tests.push(test);

sway-ast/src/expr/mod.rs

@@ -30,6 +30,10 @@ pub enum Expr {
         return_token: ReturnToken,
         expr_opt: Option<Box<Expr>>,
     },
+    Panic {
+        panic_token: PanicToken,
+        expr_opt: Option<Box<Expr>>,
+    },
     If(IfExpr),
     Match {
         match_token: MatchToken,
@@ -223,6 +227,17 @@ impl Spanned for Expr {
                 };
                 Span::join(start, &end)
             }
+            Expr::Panic {
+                panic_token,
+                expr_opt,
+            } => {
+                let start = panic_token.span();
+                let end = match expr_opt {
+                    Some(expr) => expr.span(),
+                    None => panic_token.span(),
+                };
+                Span::join(start, &end)
+            }
             Expr::If(if_expr) => if_expr.span(),
             Expr::Match {
                 match_token,
@@ -566,6 +581,7 @@ impl Expr {
             | Expr::Parens(..)
             | Expr::Array(..)
             | Expr::Return { .. }
+            | Expr::Panic { .. }
             | Expr::FuncApp { .. }
             | Expr::Index { .. }
             | Expr::MethodCall { .. }
@@ -613,6 +629,7 @@ impl Expr {
             Expr::Array(_) => "array",
             Expr::Asm(_) => "assembly block",
             Expr::Return { .. } => "return",
+            Expr::Panic { .. } => "panic",
             Expr::If(_) => "if expression",
             Expr::Match { .. } => "match expression",
             Expr::While { .. } => "while loop",

sway-ast/src/keywords.rs

@@ -84,6 +84,7 @@ define_keyword!(ConfigurableToken, "configurable");
 define_keyword!(TypeToken, "type");
 define_keyword!(PtrToken, "__ptr");
 define_keyword!(SliceToken, "__slice");
+define_keyword!(PanicToken, "panic");
 
 /// The type is a token.
 pub trait Token: Spanned + Sized {

sway-ast/src/pattern.rs

@@ -15,7 +15,7 @@ pub enum Pattern {
     /// A pattern made of a single ident, which could either be a variable or an enum variant
     AmbiguousSingleIdent(Ident),
     Var {
-        reference: Option<RefToken>, // TODO-IG: Implement `ref`, `mut`, and `ref mut` when implementing matching of references.
+        reference: Option<RefToken>, // TODO: (REFERENCES) Implement `ref`, `mut`, and `ref mut` when implementing matching of references.
         mutable: Option<MutToken>,
         name: Ident,
     },

sway-core/src/abi_generation/abi_str.rs

@@ -199,7 +199,7 @@ impl TypeInfo {
                 referenced_type,
             } => {
                 format!(
-                    "__ref {}{}", // TODO-IG: No references in ABIs according to the RFC. Or we want to have them?
+                    "__ref {}{}", // TODO: (REFERENCES) No references in ABIs according to the RFC. Or we want to have them?
                     if *to_mutable_value { "mut " } else { "" },
                     referenced_type.abi_str(ctx, engines, false)
                 )

sway-core/src/abi_generation/evm_abi.rs

@@ -140,7 +140,7 @@ pub fn abi_str(type_info: &TypeInfo, engines: &Engines) -> String {
             referenced_type,
         } => {
             format!(
-                "__ref {}{}", // TODO-IG: No references in ABIs according to the RFC. Or we want to have them?
+                "__ref {}{}", // TODO: (REFERENCES) No references in ABIs according to the RFC. Or we want to have them?
                 if *to_mutable_value { "mut " } else { "" },
                 abi_str_type_arg(referenced_type, engines)
             )

sway-core/src/asm_generation/fuel/fuel_asm_builder.rs

@@ -2094,7 +2094,7 @@ impl<'ir, 'eng> FuelAsmBuilder<'ir, 'eng> {
 
     // ---------------------------------------------------------------------------------------------
 
-    // TODO-IG: Reassess all the places we use `is_copy_type`.
+    // TODO: (REFERENCES) Reassess all the places where we use `is_copy_type`.
     pub(crate) fn is_copy_type(&self, ty: &Type) -> bool {
         ty.is_unit(self.context)
             || ty.is_never(self.context)

sway-core/src/control_flow_analysis/analyze_return_paths.rs

@@ -136,7 +136,11 @@ impl<'cfg> ControlFlowGraph<'cfg> {
 enum NodeConnection {
     /// This represents a node that steps on to the next node.
     NextStep(Option<NodeIndex>),
-    /// This represents a return or implicit return node, which aborts the stepwise flow.
+    /// This represents a node which aborts the stepwise flow.
+    /// Such nodes are:
+    /// - return expressions,
+    /// - implicit returns,
+    /// - panic expressions.
     Return(NodeIndex),
 }
 
@@ -154,6 +158,10 @@ fn connect_node<'eng: 'cfg, 'cfg>(
         | ty::TyAstNodeContent::Expression(ty::TyExpression {
             expression: ty::TyExpressionVariant::ImplicitReturn(..),
             ..
+        })
+        | ty::TyAstNodeContent::Expression(ty::TyExpression {
+            expression: ty::TyExpressionVariant::Panic(..),
+            ..
         }) => {
             let this_index = graph.add_node(ControlFlowGraphNode::from_node(node));
             if let Some(leaf_ix) = leaf_opt {