cli: support BOA_TRACE env flag for VM trace mode

cli/src/main.rs

@@ -112,7 +112,11 @@ struct Opt {
     #[allow(clippy::option_option)]
     dump_ast: Option<Option<DumpFormat>>,
 
-    /// Dump the AST to stdout with the given format.
+    /// Enable VM instruction tracing.
+    ///
+    /// This can also be enabled with the `BOA_TRACE` environment variable using
+    /// one of the following values: `1`, `true`, `yes`, `on`, `0`, `false`,
+    /// `no`, `off`.
     #[arg(long, short, conflicts_with = "graph")]
     trace: bool,
 
@@ -180,6 +184,39 @@ impl Opt {
     }
 }
 
+fn parse_bool_env_var(name: &str, value: &str) -> Result<bool> {
+    let value = value.trim();
+    if ["1", "true", "yes", "on"]
+        .iter()
+        .any(|candidate| value.eq_ignore_ascii_case(candidate))
+    {
+        return Ok(true);
+    }
+
+    if ["0", "false", "no", "off"]
+        .iter()
+        .any(|candidate| value.eq_ignore_ascii_case(candidate))
+    {
+        return Ok(false);
+    }
+
+    Err(eyre!(
+        "{name} has invalid value `{value}`; expected one of: 1, true, yes, on, 0, false, no, off"
+    ))
+}
+
+fn resolve_trace_flag(cli_trace: bool) -> Result<bool> {
+    if cli_trace {
+        return Ok(true);
+    }
+
+    match std::env::var("BOA_TRACE") {
+        Ok(value) => parse_bool_env_var("BOA_TRACE", &value),
+        Err(std::env::VarError::NotPresent) => Ok(false),
+        Err(std::env::VarError::NotUnicode(_)) => Err(eyre!("BOA_TRACE must be valid UTF-8")),
+    }
+}
+
 /// The different types of format available for dumping.
 #[derive(Debug, Copy, Clone, Default, ValueEnum)]
 enum DumpFormat {
@@ -553,8 +590,8 @@ fn main() -> Result<()> {
     // Add `console`.
     add_runtime(printer.clone(), context);
 
-    // Trace Output
-    context.set_trace(args.trace);
+    // Trace output (`--trace` or BOA_TRACE=...).
+    context.set_trace(resolve_trace_flag(args.trace)?);
 
     if args.debug_object {
         init_boa_debug_object(context);
@@ -799,3 +836,35 @@ fn add_runtime(printer: SharedExternalPrinterLogger, context: &mut Context) {
     )
     .expect("should not fail while registering the runtime");
 }
+
+#[cfg(test)]
+mod tests {
+    use super::parse_bool_env_var;
+
+    #[test]
+    fn parse_bool_env_var_accepts_truthy_values() {
+        assert!(parse_bool_env_var("BOA_TRACE", "1").unwrap());
+        assert!(parse_bool_env_var("BOA_TRACE", "true").unwrap());
+        assert!(parse_bool_env_var("BOA_TRACE", "TRUE").unwrap());
+        assert!(parse_bool_env_var("BOA_TRACE", "yes").unwrap());
+        assert!(parse_bool_env_var("BOA_TRACE", "on").unwrap());
+        assert!(parse_bool_env_var("BOA_TRACE", "  on  ").unwrap());
+    }
+
+    #[test]
+    fn parse_bool_env_var_accepts_falsy_values() {
+        assert!(!parse_bool_env_var("BOA_TRACE", "0").unwrap());
+        assert!(!parse_bool_env_var("BOA_TRACE", "false").unwrap());
+        assert!(!parse_bool_env_var("BOA_TRACE", "FALSE").unwrap());
+        assert!(!parse_bool_env_var("BOA_TRACE", "no").unwrap());
+        assert!(!parse_bool_env_var("BOA_TRACE", "off").unwrap());
+        assert!(!parse_bool_env_var("BOA_TRACE", "  off  ").unwrap());
+    }
+
+    #[test]
+    fn parse_bool_env_var_rejects_invalid_values() {
+        assert!(parse_bool_env_var("BOA_TRACE", "").is_err());
+        assert!(parse_bool_env_var("BOA_TRACE", "2").is_err());
+        assert!(parse_bool_env_var("BOA_TRACE", "maybe").is_err());
+    }
+}

docs/debugging.md

@@ -40,6 +40,21 @@ cargo run -- --dump-ast # AST dump format is Debug by default.
 Once the AST has been generated, boa will compile it into bytecode, which is then executed by the VM.
 You can print the bytecode and the executed instructions with the command-line flag `--trace`.
 
+For non-interactive workflows (scripts, CI, wrappers), you can also enable the same
+trace mode via the `BOA_TRACE` environment variable:
+
+```bash
+BOA_TRACE=1 cargo run -- test.js
+```
+
+Accepted values are:
+
+- truthy: `1`, `true`, `yes`, `on`
+- falsy: `0`, `false`, `no`, `off`
+
+Values are case-insensitive and leading/trailing whitespace is ignored.
+If both are provided, `--trace` takes precedence over `BOA_TRACE`.
+
 For more detailed information about the VM and the trace output look [here](./vm.md).
 
 ## Instruction flowgraph