refactor(runtime): move $262 to boa_runtime, add --test262-object to cli

Move `$262` implementation from `tests/tester/src/exec/js262.rs` to
`core/runtime/src/test262.rs` behind a new `test262` feature gate
(pulls `bus` as optional dep). Add `annex-b` feature to boa_runtime
forwarding to `boa_engine/annex-b` for `$262.IsHTMLDDA`.

Both cli and boa_tester now use `boa_runtime/test262`, removing the
tester's direct `bus` and `boa_gc` deps.

CLI registers `$262` when `--test262-object` flag is passed.

This change makes CLI more suitable for running test262 via an external
harness such as eshost + test262-harness. The exact same `$262` object as
used by the internal boa_tester can now be directly accessed in CLI.
Existing `$boa` object doesn't expose some of the methods (like IsHTMLDDA,
detachArrayBuffer and agent helpers) needed for full test262 support,
and would have required users to maintain a custom shim mapping it to `$262`.

Fixes #5054

Author: ivankra

Cargo.lock

@@ -164,6 +164,7 @@ Options:
       --flowgraph [<FORMAT>]          Generate instruction flowgraph. Default is Graphviz [possible values: graphviz, mermaid]
       --flowgraph-direction <FORMAT>  Specifies the direction of the flowgraph. Default is top-top-bottom [possible values: top-to-bottom, bottom-to-top, left-to-right, right-to-left]
       --debug-object                  Inject debugging object `$boa`
+      --test262-object                Inject the test262 host object `$262`
   -m, --module                        Treats the input files as modules
   -r, --root <ROOT>                   Root path from where the module resolver will try to load the modules [default: .]
   -h, --help                          Print help (see more with '--help')

README.md

@@ -15,7 +15,7 @@ rust-version.workspace = true
 boa_engine = { workspace = true, features = ["deser", "float16", "flowgraph", "temporal", "trace", "xsum"] }
 boa_parser.workspace = true
 boa_gc.workspace = true
-boa_runtime.workspace = true
+boa_runtime = { workspace = true, features = ["test262"] }
 rustyline = { workspace = true, features = ["derive", "with-file-history"] }
 clap = { workspace = true, features = ["derive"] }
 serde_json.workspace = true
@@ -33,6 +33,7 @@ rustls.workspace = true
 [features]
 default = [
     "boa_engine/annex-b",
+    "boa_runtime/annex-b",
     "boa_engine/experimental",
     "boa_engine/intl_bundled",
     "boa_engine/native-backtrace",

cli/Cargo.toml

@@ -58,6 +58,7 @@ Options:
       --flowgraph [<FORMAT>]          Generate instruction flowgraph. Default is Graphviz [possible values: graphviz, mermaid]
       --flowgraph-direction <FORMAT>  Specifies the direction of the flowgraph. Default is top-top-bottom [possible values: top-to-bottom, bottom-to-top, left-to-right, right-to-left]
       --debug-object                  Inject debugging object `$boa`
+      --test262-object                Inject the test262 host object `$262`
   -m, --module                        Treats the input files as modules
   -r, --root <ROOT>                   Root path from where the module resolver will try to load the modules [default: .]
   -e, --expression <EXPR>             Execute a JavaScript expression then exit

cli/README.md

@@ -153,6 +153,10 @@ struct Opt {
     #[arg(long)]
     debug_object: bool,
 
+    /// Inject the test262 host object `$262`.
+    #[arg(long)]
+    test262_object: bool,
+
     /// Treats the input files as modules.
     #[arg(long, short = 'm', group = "mod")]
     module: bool,
@@ -562,6 +566,14 @@ fn main() -> Result<()> {
         init_boa_debug_object(context);
     }
 
+    if args.test262_object {
+        boa_runtime::test262::register_js262(
+            boa_runtime::test262::WorkerHandles::new(),
+            true, // register `console` in $262.agent worker threads
+            context,
+        );
+    }
+
     // Configure optimizer options
     let mut optimizer_options = OptimizerOptions::empty();
     optimizer_options.set(OptimizerOptions::STATISTICS, args.optimizer_statistics);

cli/src/main.rs

@@ -14,6 +14,7 @@ rust-version.workspace = true
 boa_engine.workspace = true
 base64.workspace = true
 boa_gc.workspace = true
+bus = { workspace = true, optional = true }
 bytemuck.workspace = true
 either = { workspace = true, optional = true }
 futures = "0.3.32"
@@ -57,3 +58,5 @@ fetch = [
 ]
 reqwest-blocking = ["dep:reqwest", "reqwest/blocking"]
 process = []
+annex-b = ["boa_engine/annex-b"]
+test262 = ["dep:bus"]

core/runtime/Cargo.toml

@@ -123,6 +123,8 @@ pub mod microtask;
 #[cfg(feature = "process")]
 pub mod process;
 pub mod store;
+#[cfg(feature = "test262")]
+pub mod test262;
 pub mod text;
 #[cfg(feature = "url")]
 pub mod url;

core/runtime/src/lib.rs

@@ -1,9 +1,12 @@
 use std::{
     cell::RefCell,
     rc::Rc,
-    sync::mpsc::{self, Sender},
+    sync::{
+        OnceLock,
+        mpsc::{self, Sender},
+    },
     thread::JoinHandle,
-    time::Duration,
+    time::{Duration, Instant},
 };
 
 #[cfg(feature = "annex-b")]
@@ -18,25 +21,27 @@ use boa_engine::{
 };
 use bus::BusReader;
 
-use crate::START;
+/// Monotonic clock for `$262.agent.monotonicNow()`, initialized by `register_js262()`.
+static START: OnceLock<Instant> = OnceLock::new();
 
-pub(super) enum WorkerResult {
+pub enum WorkerResult {
     Ok,
     Err(String),
     Panic(String),
 }
 
-pub(super) type WorkerHandle = JoinHandle<Result<(), String>>;
+type WorkerHandle = JoinHandle<Result<(), String>>;
 
 #[derive(Debug, Clone)]
-pub(super) struct WorkerHandles(Rc<RefCell<Vec<WorkerHandle>>>);
+pub struct WorkerHandles(Rc<RefCell<Vec<WorkerHandle>>>);
 
 impl WorkerHandles {
-    pub(super) fn new() -> Self {
+    #[must_use]
+    pub fn new() -> Self {
         Self(Rc::default())
     }
 
-    pub(super) fn join_all(&mut self) -> Vec<WorkerResult> {
+    pub fn join_all(&mut self) -> Vec<WorkerResult> {
         let handles = std::mem::take(&mut *self.0.borrow_mut());
 
         handles
@@ -71,11 +76,8 @@ impl Drop for WorkerHandles {
 }
 
 /// Creates the object $262 in the context.
-pub(super) fn register_js262(
-    handles: WorkerHandles,
-    console: bool,
-    context: &mut Context,
-) -> JsObject {
+pub fn register_js262(handles: WorkerHandles, console: bool, context: &mut Context) -> JsObject {
+    START.get_or_init(Instant::now);
     let global_obj = context.global_object();
 
     let agent = agent_obj(handles, console, context);
@@ -235,14 +237,10 @@ fn agent_obj(handles: WorkerHandles, console: bool, context: &mut Context) -> Js
                 register_js262_worker(rx, tx, context);
 
                 if console {
-                    let console = boa_runtime::Console::init(context);
+                    let console = crate::Console::init(context);
 
                     context
-                        .register_global_property(
-                            boa_runtime::Console::NAME,
-                            console,
-                            Attribute::all(),
-                        )
+                        .register_global_property(crate::Console::NAME, console, Attribute::all())
                         .expect("the console builtin shouldn't exist");
                 }
 

tests/tester/src/exec/js262.rs core/runtime/src/test262.rstests/tester/src/exec/js262.rs renamed to core/runtime/src/test262.rs

@@ -13,8 +13,7 @@ rust-version.workspace = true
 
 [dependencies]
 boa_engine = { workspace = true, features = ["float16"] }
-boa_runtime.workspace = true
-boa_gc.workspace = true
+boa_runtime = { workspace = true, features = ["test262"] }
 clap = { workspace = true, features = ["derive"] }
 serde = { workspace = true, features = ["derive"] }
 serde_yaml = "0.9.34" # TODO: Track https://github.com/saphyr-rs/saphyr.
@@ -28,11 +27,10 @@ color-eyre.workspace = true
 phf = { workspace = true, features = ["macros"] }
 comfy-table.workspace = true
 serde_repr.workspace = true
-bus.workspace = true
 cow-utils.workspace = true
 
 [features]
-annex-b = ["boa_engine/annex-b"]
+annex-b = ["boa_engine/annex-b", "boa_runtime/annex-b"]
 default = ["boa_engine/intl_bundled", "boa_engine/experimental", "annex-b"]
 
 [lints]

tests/tester/Cargo.toml

@@ -1,6 +1,6 @@
 //! Execution module for the test runner.
 
-mod js262;
+use boa_runtime::test262 as js262;
 
 use crate::{
     Harness, Outcome, Phase, SpecEdition, Statistics, SuiteResult, Test, TestFlags,
@@ -23,7 +23,7 @@ use rayon::prelude::*;
 use rustc_hash::FxHashSet;
 use std::{cell::RefCell, eprintln, path::Path, rc::Rc};
 
-use self::js262::WorkerHandles;
+use js262::WorkerHandles;
 
 impl TestSuite {
     /// Runs the test suite.