[compiler] New macros using abort with message

[calintat]

Description

This PR introduces new assertion macros built on top of the overloaded abort added in an earlier PR.

New assert! form

This now supports formatted messages with arguments:

assert!(cond, fmt, arg1, ..., argN)

// expands to
if (cond) {
    ()
} else {
    abort string_utils::format<N>(&fmt, arg1, ..., argN)
}

Example:

let x = 12;
assert!(x < 10, b"Expected x to be less than 10, but got {}", x)

which aborts with message:

Expected x to be less than 10, but got 12

New assert_eq! and assert_ne! macros

These macros mirror the behaviour and ergonomics of Rust’s assert_eq! and assert_ne!, including structured evaluation and rich error messages. There are three forms depending on the number of arguments.

Two arguments

assert_eq!(left, right)

// expands to
match ((left, right)) {
    (_left, _right) => {
        if (_left == _right) {
            ()
        } else {
            abort string::into_bytes(string_utils::format2(<assertion_failed_message>, _left, _right))
        }
    }
}

Three arguments (custom message)

assert_eq!(left, right, message)

// expands to
match ((left, right)) {
    (_left, _right) => {
        if (_left == _right) {
            ()
        } else {
            abort string::into_bytes(string_utils::format3(<assertion_failed_message>, string::utf8(message), _left, _right))
        }
    }
}

More than three arguments (formatted message)

assert_eq!(left, right, fmt, arg1, ..., argN)

// expands to
match ((left, right)) {
    (_left, _right) => {
        if (_left == _right) {
            ()
        } else {
            abort string::into_bytes(string_utils::format3(<assertion_failed_message>, string_utils::format<N>(&fmt, arg1, ..., argN), _left, _right))
        }
    }
}

Assertion failed message format

The assertion failure message format is inspired by Rust and shows both evaluated values:

assertion failed `left == right`
  left: <left>
 right: <right>

It can also include a custom message:

assertion failed `left == right`: <message>
  left: <left>
 right: <right>

How Has This Been Tested?

Added unit tests for all possible forms of assert!, assert_eq!, and assert_ne!.

Key Areas to Review

Type of Change

• New feature
• Bug fix
• Breaking change
• Performance improvement
• Refactoring
• Dependency update
• Documentation update
• Tests

Which Components or Systems Does This Change Impact?

• Validator Node
• Full Node (API, Indexer, etc.)
• Move/Aptos Virtual Machine
• Aptos Framework
• Aptos CLI/SDK
• Developer Infrastructure
• Move Compiler
• Other (specify)

Checklist

• I have read and followed the CONTRIBUTING doc
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I identified and added all stakeholders and component owners affected by this change as reviewers
• I tested both happy and unhappy path of the functionality
• I have made corresponding changes to the documentation

---

Note

Introduces assertion macros with rich messages and compiler support.

• Implements macro expansion for assert!, assert_eq!, and assert_ne! in move-model/src/builder/macros.rs, generating conditionals/matches and formatted messages via std::string/std::string_utils
• Extends well-known modules and ensures implicit inclusion of vector, cmp, string, and string_utils during dependency closure; adds helpers for UTF8/bytes conversion
• Adds string::into_bytes to stdlib string.move
• Updates tests: new e2e transactional tests (macros.rs, Move package) and numerous compiler/bytecode/typing/naming/macros test expectations; adds a macros test config
• Minor infra tweaks: decompiler tests exclude vector.move, docgen link adjustments

^{Written by Cursor Bugbot for commit 965eee0. This will update automatically on new commits. Configure here.}

[calintat]

• [compiler] New macros using abort with message #18412 👈 (View in Graphite)
• [compiler] Overload Move abort to support messages #18403
• [vm] New bytecode for aborting with message #18347
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[calintat]

Re-drafting this following discussion in standup. Need to enforce the message is a constant.

[junxzm1990]

It's nice to reuse std functions. I am just a bit worried about dependencies. If the users do not explicitly import string_utils/string, the dependency between the current module and string_utils/string will not be built. In result, the users may see an error message saying that string_utils/string is not bound, creating some confusion.

Maybe you can do some tests using the CLI to compile an exmple with assert_eq! but does not include any dependency in its Move.toml, and see what happens.

We used to face similar problems when dealing with std::vector and std::cmp. Here is a trick we did to avoid such problems:
https://github.com/aptos-labs/aptos-core/pull/16812/files#diff-9b8fbd37b0c05da93fc009674561ea37f0fdc242b021e9ce5300358e717368f2. Meanwhile, we were better positioned to check if the std::cmp module is present as we already have the move model: https://github.com/aptos-labs/aptos-core/pull/16812/files#diff-17c49bd2efe73148cec80384375c0a69d31778daafd97196485318719fdb7a74R184

[calintat]

Maybe you can do some tests using the CLI to compile an exmple with assert_eq! but does not include any dependency in its Move.toml, and see what happens.

It will give an error message that the function names are not bound, e.g.

error: no function named `string::into_bytes` found
  ┌─ ./sources/test.move:4:9
  │
4 │         assert_eq!(1, 2);
  │         ^^^^^^^^^

error: no function named `string_utils::format2` found
  ┌─ ./sources/test.move:4:9
  │
4 │         assert_eq!(1, 2);

[calintat]

OK, I did a similar trick to what we do for cmp and vector. Now, if you try to use assert_eq! without having either move-stdlib or aptos-stdlib in your dependencies, you’ll get a more helpful error:

error: cannot find `string_utils` module
  ┌─ ./sources/test.move:4:9
  │
9 │         assert_eq!(1, 2);
  │         ^^^^^^^^^

error: cannot find `string` module
  ┌─ ./sources/test.move:4:9
  │
9 │         assert_eq!(1, 2);
  │         ^^^^^^^^^

[junxzm1990]

This looks better.

It feels even nicer if we could let users know that they need to incldue move-stdlib as a dependency when using assert with strings, which is, however, not doable here as dependencies may not have been resolved. Maybe we should do an AST rewrite after the movel model is built, but that would be a different implementation.

Anyways, time to move forward.

[wrwg]

Nice work!