Merge pull request #6497 from jferrant/chore/aac-rename-parse-errors

Chore/aac rename parse errors and add descriptions

Author: Jiloc

clarity-types/src/errors/ast.rs

@@ -21,7 +21,7 @@ pub mod lexer;
 use std::{error, fmt};
 
 pub use analysis::{CheckErrorKind, StaticCheckError};
-pub use ast::{ParseError, ParseErrors, ParseResult};
+pub use ast::{ParseError, ParseErrorKind, ParseResult};
 pub use cost::CostErrors;
 pub use lexer::LexerError;
 #[cfg(feature = "rusqlite")]
@@ -33,8 +33,12 @@ use crate::types::{FunctionIdentifier, Value};
 
 pub type StackTrace = Vec<FunctionIdentifier>;
 
+/// Wraps error types that do not implement [`PartialEq`], enabling their
+/// use in enums that implement the trait. Any two `IncomparableError` values
+/// are always considered unequal.
 #[derive(Debug)]
 pub struct IncomparableError<T> {
+    /// The wrapped error value.
     pub err: T,
 }
 
@@ -52,70 +56,141 @@ pub enum VmExecutionError {
     /// violating type or resource constraints (e.g., excessive stack depth).
     /// The `CheckErrorKind` wraps the specific type-checking error encountered at runtime.
     Unchecked(CheckErrorKind),
-    Interpreter(InterpreterError),
+    /// A critical, unrecoverable bug within the VM's internal logic.
+    ///
+    /// The presence of this error indicates a violation of one of the VM's
+    /// invariants or a corrupted state. This is **not** an error in the user's
+    /// Clarity code, but a bug in the VM's Rust implementation.
+    ///
+    /// # Example
+    /// The VM's evaluation loop attempts to `pop` from an empty internal call stack,
+    /// indicating a mismatch in function entry/exit logic.
+    Internal(VmInternalError),
     /// Errors that occur during runtime execution of Clarity code, such as arithmetic errors or
     /// invalid operations, expected as part of contract evaluation.
     /// The `RuntimeErrorType` wraps the specific runtime error, and the `Option<StackTrace>` provides
     /// an optional stack trace for debugging, if available.
-    Runtime(RuntimeErrorType, Option<StackTrace>),
+    Runtime(RuntimeError, Option<StackTrace>),
     /// Errors triggered during Clarity contract evaluation that cause early termination with
     /// insufficient results (e.g., unwrapping an empty `Option`).
     /// The `EarlyReturnError` wraps the specific early return condition, detailing the premature
     /// termination cause.
     EarlyReturn(EarlyReturnError),
 }
 
-/// InterpreterErrors are errors that *should never* occur.
-/// Test executions may trigger these errors.
+/// Represents an internal, unrecoverable error within the Clarity VM.
+///
+/// These errors signify a bug in the VM's logic or a violation of its internal
+/// invariants. They are not meant to be caught or handled by Clarity contracts.
 #[derive(Debug, PartialEq)]
-pub enum InterpreterError {
+pub enum VmInternalError {
+    /// Raised when the VM encounters an invalid or malformed `SymbolicExpression`
+    /// e.g., bad variable name or missing argument.
+    /// The `String` provides a message describing the specific issue.
     BadSymbolicRepresentation(String),
-    InterpreterError(String),
+    /// A generic, unexpected internal error, indicating a logic failure within
+    /// the VM.
+    /// The `String` provides a message describing the specific failure.
+    InvariantViolation(String), // TODO: merge with VmInternalError::Expect
+    /// The VM failed to produce the final `AssetMap` when finalizing the
+    /// execution environment for a transaction.
     FailedToConstructAssetTable,
+    /// The VM failed to produce the final `EventBatch` when finalizing the
+    /// execution environment for a transaction.
     FailedToConstructEventBatch,
+    /// An error occurred during an interaction with the database.
+    /// The parameter contains the corresponding SQLite error.
     #[cfg(feature = "rusqlite")]
     SqliteError(IncomparableError<SqliteError>),
+    /// The file path provided for the MARF database is invalid because it
+    /// contains non-UTF-8 characters.
     BadFileName,
+    /// The VM failed to create the necessary directory for the MARF persistent
+    /// storage. Likely due to a file system permissions error or an invalid path
     FailedToCreateDataDirectory,
+    /// A failure occurred within the MARF implementation.
+    /// The `String` provides a message describing the specific failure.
     MarfFailure(String),
+    /// Failed to construct a tuple value from provided data because it did not
+    ///  match the expected type signature.
     FailureConstructingTupleWithType,
+    /// Failed to construct a list value from provided data because it
+    /// did not match the expected type signature.
     FailureConstructingListWithType,
+    /// An STX transfer failed due to insufficient balance.
     InsufficientBalance,
+    /// A generic error occurred during a database operation.
+    /// The `String` represents a descriptive message detailing the specific issue.
     DBError(String),
+    /// An internal expectation or assertion failed. This is used for conditions
+    /// that are believed to be unreachable but are handled gracefully to prevent
+    /// a panic.
+    /// The `String` provides a message describing the failed expectation.
     Expect(String),
 }
 
-/// RuntimeErrors are errors that smart contracts are expected
-///   to be able to trigger during execution (e.g., arithmetic errors)
+/// Runtime errors that Clarity smart contracts are expected to trigger during execution in the virtual
+/// machine, such as arithmetic errors, invalid operations, or blockchain-specific issues. These errors
+/// are distinct from static analysis errors and occur during dynamic evaluation of contract code.
 #[derive(Debug, PartialEq)]
-pub enum RuntimeErrorType {
+pub enum RuntimeError {
+    /// A generic arithmetic error encountered during contract execution.
+    /// The `String` represents a descriptive message detailing the specific arithmetic issue.
     Arithmetic(String),
+    /// An arithmetic operation exceeded the maximum value for the data type (e.g., `u128`).
     ArithmeticOverflow,
+    /// An arithmetic operation resulted in a value below zero for an unsigned type.
     ArithmeticUnderflow,
+    /// Attempt to increase token supply beyond the maximum limit.
+    /// The first u128 represents the attempted new supply (current supply plus increase),
+    /// and the second represents the maximum allowed supply.
     SupplyOverflow(u128, u128),
+    /// Attempt to decrease token supply below zero.
+    /// The first `u128` represents the current token supply, and the second represents the attempted decrease amount.
     SupplyUnderflow(u128, u128),
+    /// Attempt to divide or compute modulo by zero.
     DivisionByZero,
-    // error in parsing types
-    ParseError(String),
-    // error in parsing the AST
+    /// Failure to parse types dynamically during contract execution.
+    /// The `String` represents the specific parsing issue, such as invalid data formats.
+    TypeParseFailure(String),
+    /// Failure to parse the abstract syntax tree (AST) during dynamic evaluation.
+    /// The `Box<ParseError>` wraps the specific parsing error encountered, detailing code interpretation issues.
     ASTError(Box<ParseError>),
+    /// The call stack exceeded the virtual machine's maximum depth.
     MaxStackDepthReached,
+    /// The execution context depth exceeded the virtual machine's limit.
     MaxContextDepthReached,
+    /// Attempt to construct an invalid or unsupported type at runtime (e.g., malformed data structure).
     BadTypeConstruction,
+    /// Reference to an invalid or out-of-bounds block height.
+    /// The `String` represents the string representation of the queried block height that was invalid.
     BadBlockHeight(String),
+    /// Attempt to interact with a non-existent token (e.g., in NFT or fungible token operations).
     NoSuchToken,
+    /// Feature or function not yet implemented in the virtual machine.
     NotImplemented,
+    /// No caller principal available in the current execution context.
     NoCallerInContext,
+    /// No sender principal available in the current execution context.
     NoSenderInContext,
+    /// Invalid name-value pair in contract data (e.g., map keys).
+    /// The `&'static str` represents the name of the invalid pair, and the `String` represents the offending value.
     BadNameValue(&'static str, String),
+    /// Reference to a non-existent block header hash.
+    /// The `BlockHeaderHash` represents the unknown block header hash.
     UnknownBlockHeaderHash(BlockHeaderHash),
+    /// Invalid block hash provided (e.g., incorrect format or length).
+    /// The `Vec<u8>` represents the invalid block hash data.
     BadBlockHash(Vec<u8>),
+    /// Failed to unwrap an `Optional` (`none`) or `Response` (`err` or `ok`) Clarity value.
     UnwrapFailure,
+    /// Attempt to set metadata (e.g., for NFTs or tokens) that was already initialized.
     MetadataAlreadySet,
-    // pox-locking errors
+    /// Interaction with a deprecated or inactive Proof of Transfer (PoX) contract.
     DefunctPoxContract,
+    /// Attempt to lock STX for stacking when already locked in an active PoX cycle.
     PoxAlreadyLocked,
-
+    /// Block time unavailable during execution.
     BlockTimeNotAvailable,
 }
 
@@ -146,7 +221,7 @@ impl PartialEq<VmExecutionError> for VmExecutionError {
             (VmExecutionError::Runtime(x, _), VmExecutionError::Runtime(y, _)) => x == y,
             (VmExecutionError::Unchecked(x), VmExecutionError::Unchecked(y)) => x == y,
             (VmExecutionError::EarlyReturn(x), VmExecutionError::EarlyReturn(y)) => x == y,
-            (VmExecutionError::Interpreter(x), VmExecutionError::Interpreter(y)) => x == y,
+            (VmExecutionError::Internal(x), VmExecutionError::Internal(y)) => x == y,
             _ => false,
         }
     }
@@ -170,7 +245,7 @@ impl fmt::Display for VmExecutionError {
     }
 }
 
-impl fmt::Display for RuntimeErrorType {
+impl fmt::Display for RuntimeError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> std::fmt::Result {
         write!(f, "{self:?}")
     }
@@ -182,7 +257,7 @@ impl error::Error for VmExecutionError {
     }
 }
 
-impl error::Error for RuntimeErrorType {
+impl error::Error for RuntimeError {
     fn source(&self) -> Option<&(dyn error::Error + 'static)> {
         None
     }
@@ -191,30 +266,30 @@ impl error::Error for RuntimeErrorType {
 impl From<ParseError> for VmExecutionError {
     fn from(err: ParseError) -> Self {
         match *err.err {
-            ParseErrors::InterpreterFailure => VmExecutionError::from(InterpreterError::Expect(
+            ParseErrorKind::InterpreterFailure => VmExecutionError::from(VmInternalError::Expect(
                 "Unexpected interpreter failure during parsing".into(),
             )),
-            _ => VmExecutionError::from(RuntimeErrorType::ASTError(Box::new(err))),
+            _ => VmExecutionError::from(RuntimeError::ASTError(Box::new(err))),
         }
     }
 }
 
 impl From<CostErrors> for VmExecutionError {
     fn from(err: CostErrors) -> Self {
         match err {
-            CostErrors::InterpreterFailure => VmExecutionError::from(InterpreterError::Expect(
+            CostErrors::InterpreterFailure => VmExecutionError::from(VmInternalError::Expect(
                 "Interpreter failure during cost calculation".into(),
             )),
-            CostErrors::Expect(s) => VmExecutionError::from(InterpreterError::Expect(format!(
+            CostErrors::Expect(s) => VmExecutionError::from(VmInternalError::Expect(format!(
                 "Interpreter failure during cost calculation: {s}"
             ))),
             other_err => VmExecutionError::from(CheckErrorKind::from(other_err)),
         }
     }
 }
 
-impl From<RuntimeErrorType> for VmExecutionError {
-    fn from(err: RuntimeErrorType) -> Self {
+impl From<RuntimeError> for VmExecutionError {
+    fn from(err: RuntimeError) -> Self {
         VmExecutionError::Runtime(err, None)
     }
 }
@@ -237,9 +312,9 @@ impl From<EarlyReturnError> for VmExecutionError {
     }
 }
 
-impl From<InterpreterError> for VmExecutionError {
-    fn from(err: InterpreterError) -> Self {
-        VmExecutionError::Interpreter(err)
+impl From<VmInternalError> for VmExecutionError {
+    fn from(err: VmInternalError) -> Self {
+        VmExecutionError::Internal(err)
     }
 }
 
@@ -272,15 +347,13 @@ mod test {
             ))))
         );
         assert_eq!(
-            VmExecutionError::Interpreter(InterpreterError::InterpreterError("".to_string())),
-            VmExecutionError::Interpreter(InterpreterError::InterpreterError("".to_string()))
+            VmExecutionError::Internal(VmInternalError::InvariantViolation("".to_string())),
+            VmExecutionError::Internal(VmInternalError::InvariantViolation("".to_string()))
         );
         assert!(
             VmExecutionError::EarlyReturn(EarlyReturnError::UnwrapFailed(Box::new(Value::Bool(
                 true
-            )))) != VmExecutionError::Interpreter(InterpreterError::InterpreterError(
-                "".to_string()
-            ))
+            )))) != VmExecutionError::Internal(VmInternalError::InvariantViolation("".to_string()))
         );
     }
 }

clarity-types/src/errors/mod.rs

@@ -23,7 +23,7 @@ use regex::Regex;
 use stacks_common::codec::{Error as codec_error, StacksMessageCodec, read_next, write_next};
 
 use crate::Value;
-use crate::errors::RuntimeErrorType;
+use crate::errors::RuntimeError;
 use crate::types::TraitIdentifier;
 
 pub const CONTRACT_MIN_NAME_LENGTH: usize = 1;
@@ -66,17 +66,17 @@ guarded_string!(
     "ClarityName",
     CLARITY_NAME_REGEX,
     MAX_STRING_LEN,
-    RuntimeErrorType,
-    RuntimeErrorType::BadNameValue
+    RuntimeError,
+    RuntimeError::BadNameValue
 );
 
 guarded_string!(
     ContractName,
     "ContractName",
     CONTRACT_NAME_REGEX,
     MAX_STRING_LEN,
-    RuntimeErrorType,
-    RuntimeErrorType::BadNameValue
+    RuntimeError,
+    RuntimeError::BadNameValue
 );
 
 impl StacksMessageCodec for ClarityName {

clarity-types/src/representations.rs

@@ -15,7 +15,7 @@
 
 use rstest::rstest;
 
-use crate::errors::RuntimeErrorType;
+use crate::errors::RuntimeError;
 use crate::representations::{
     CONTRACT_MAX_NAME_LENGTH, CONTRACT_MIN_NAME_LENGTH, ClarityName, ContractName, MAX_STRING_LEN,
 };
@@ -73,7 +73,7 @@ fn test_clarity_name_invalid(#[case] name: &str) {
     assert!(result.is_err());
     assert!(matches!(
         result.unwrap_err(),
-        RuntimeErrorType::BadNameValue(_, _)
+        RuntimeError::BadNameValue(_, _)
     ));
 }
 
@@ -157,7 +157,7 @@ fn test_contract_name_invalid(#[case] name: &str) {
     assert!(result.is_err());
     assert!(matches!(
         result.unwrap_err(),
-        RuntimeErrorType::BadNameValue(_, _)
+        RuntimeError::BadNameValue(_, _)
     ));
 }